413 Request Entity Too Large: causas e correções

O que significa 413 Payload Too Large

A RFC 9110 define o nome atual como 413 Content Too Large, embora 413 Payload Too Large e o nome mais antigo 413 Request Entity Too Large se refiram ao mesmo código de status e ainda apareçam em servidores, frameworks e páginas de erro. Seja qual for a redação, o significado é idêntico: a requisição em si estava sintaticamente correta, mas o corpo dela ultrapassou um limite de tamanho antes de o servidor aceitá-la para processamento. Isso acontece mais frequentemente em upload de arquivos, mas pode acontecer em qualquer requisição com um corpo grande, incluindo um payload de API em massa.

Como o erro aparece

Navegadores geralmente mostram a página de erro simples que o servidor de origem ou a borda devolveu; não existe uma interface dedicada do navegador para isso como existe para uma falha de conexão. É comum ver isso falhar silenciosamente em um formulário, com a resposta visível só na aba de rede, especialmente em um upload de arquivo construído com JavaScript. Na linha de comando, a resposta confirma direto:

curl -i -X POST -F "[email protected]" https://example.com/upload
HTTP/1.1 413 Request Entity Too Large
Content-Type: text/html

Os logs de acesso e de erro do servidor são o lugar mais confiável para confirmar o tamanho exato envolvido e qual camada rejeitou a requisição, já que ela pode ser bloqueada na CDN, no servidor web ou na aplicação, e cada um registra isso de forma diferente.

O que causa um 413

• O client_max_body_size do nginx. O padrão é 1 MB, um valor pequeno o suficiente para que quase qualquer upload real de arquivo tropece nele até ser elevado explicitamente:

  client_max_body_size 20M;

• O LimitRequestBody do Apache. Definido por diretório ou globalmente e, assim como no nginx, tem um valor padrão que muitas aplicações excedem sem que ninguém tenha mudado de propósito.
• O upload_max_filesize e o post_max_size do PHP. Duas configurações separadas no php.ini que precisam ser grandes o suficiente para o upload; o post_max_size precisa ser pelo menos tão grande quanto o upload_max_filesize ou a segunda configuração limita a primeira silenciosamente.
• O maxAllowedContentLength do IIS. Definido no web.config sob requestLimits, com padrão de cerca de 30 MB, e separado da configuração maxRequestLength do próprio ASP.NET, que usa unidades diferentes e precisa ser elevada junto com ele.
• O limite de upload baseado em plano da Cloudflare. Os planos Free e Pro limitam o tamanho do corpo da requisição em 100 MB independentemente do que o servidor de origem aceitaria de outra forma, e esse limite não pode ser elevado a partir da configuração da própria origem; precisa ser resolvido do lado da Cloudflare ou contornado com um caminho de upload direto que passa por fora do proxy.
• Limites de payload de API gateways. Gateways de API gerenciados costumam limitar o corpo da requisição bem abaixo do que um servidor web tradicional permitiria, geralmente na casa de poucos megabytes, o que pega equipes migrando uma funcionalidade de upload existente para trás de um novo gateway.

Como saber de quem é a culpa

Isso quase nunca é culpa de um visitante no sentido de ter feito algo errado; o arquivo que ele está enviando é simplesmente maior do que um limite que existe em algum ponto da cadeia, e a correção pertence a quem quer que seja o dono daquela camada. Se o mesmo arquivo sobe sem problema em um ambiente e falha em outro, compare cada camada no caminho da requisição, já que nginx, PHP e uma CDN podem ter limites diferentes, e o menor deles vence. Rodar uma verificação HTTP com um corpo de requisição perto do limite pretendido, enviada de fora da sua rede, confirma qual é o teto efetivo de ponta a ponta em vez de confiar em um único arquivo de configuração.

Como corrigir um erro 413

Se você é um visitante

1. Comprima o arquivo antes de enviar, especialmente imagens e vídeos, que costumam encolher drasticamente sem perda visível de qualidade em tamanhos típicos.
2. Divida um upload grande em partes menores se o site suportar upload em blocos ou retomável, em vez de enviar uma requisição muito grande de uma vez.
3. Confira o limite de upload declarado pelo site, se houver um publicado, já que alguns 413 estão funcionando como pretendido e a correção é simplesmente um arquivo menor.

Se você administra o site

1. Eleve o limite em toda camada junto, não só em uma. Uma única requisição normalmente passa por uma CDN, um servidor web e um runtime de aplicação, e o menor limite configurado em qualquer ponto dessa cadeia determina o teto real.
2. Defina nginx e Apache explicitamente em vez de confiar nos padrões:

   # nginx
   client_max_body_size 20M;
   
   # Apache
   LimitRequestBody 20971520

3. Faça as duas configurações do PHP combinarem. Eleve tanto o upload_max_filesize quanto o post_max_size, e garanta que o segundo seja igual ou maior que o primeiro.
4. Atualize o requestLimits do IIS e o maxRequestLength do ASP.NET juntos no web.config, já que eles medem a mesma coisa em unidades diferentes e ambos precisam ser elevados.
5. Contorne o limite de plano da Cloudflare para arquivos genuinamente grandes fazendo upload direto para o armazenamento com uma URL assinada, passando por fora do caminho de requisição via proxy inteiramente, em vez de tentar elevar um limite que aquele plano não expõe.
6. Verifique o limite de payload do próprio API gateway separadamente do serviço de backend, se houver um na frente da sua aplicação; ele pode rejeitar uma requisição antes que as suas próprias configurações de aplicação, mais generosas, tenham a chance de se aplicar.

Como prevenir um 413 bloqueando usuários reais

Um limite definido baixo demais é fácil de passar despercebido até alguém com um arquivo grande esbarrar nele, e nesse ponto parece uma funcionalidade de upload quebrada em vez de um limite de configuração desalinhado. Uma verificação HTTP agendada que envia uma requisição perto do seu limite de tamanho pretendido, com uma asserção no código de status esperado, confirma que a cadeia inteira ainda aceita depois de qualquer mudança na CDN, no servidor web ou na configuração da aplicação. Combinado com monitoramento de várias localidades, isso também pega um limite no nível da CDN que só se aplica em certos nós de borda.

Erros relacionados

Veja 400 Bad Request, que alguns servidores devolvem no lugar de 413 para a mesma condição de corpo grande demais, a visão geral dos 4xx para a família mais ampla, e 406 Not Acceptable em outro ponto deste lote.

Perguntas frequentes

413 Payload Too Large é o mesmo que 413 Request Entity Too Large?

Sim. A RFC 9110 renomeou o texto do status para 413 Content Too Large, mas os dois nomes antigos se referem ao mesmo código de status e ao mesmo significado, e as três formulações ainda aparecem no mundo real dependendo da versão do software do servidor.

Por que meu upload falha mesmo depois de eu elevar o client_max_body_size do nginx?

Outra camada na cadeia, comumente o post_max_size do PHP, um limite fixo de plano de CDN, ou um API gateway, provavelmente está impondo um limite menor de forma independente. Toda camada entre o cliente e a aplicação precisa permitir o tamanho, não só a que você mudou.

Posso elevar o limite de 100 MB da Cloudflare no plano free ou pro?

Não a partir da própria configuração do servidor de origem; esse teto é fixo pelo nível de plano. A saída costumeira é fazer upload de arquivos grandes direto para o armazenamento usando uma URL assinada que passa por fora do caminho de requisição via proxy.

Um 413 conta como um bloqueio de segurança?

Normalmente não. Costuma ser um limite de recurso direto em vez de uma regra defensiva, embora alguns WAFs usem corpos incomumente grandes como um sinal entre vários ao decidir se bloqueiam uma requisição.

Qual é um limite de upload padrão razoável se eu ainda não defini nenhum?

Não existe um número universal; depende inteiramente do que a sua aplicação legitimamente precisa aceitar. Defina isso deliberadamente com base no seu maior arquivo legítimo esperado, em vez de deixar o padrão de cada camada como está.