HTTP 413 Content Too Large: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, ferramenta de upload ou verificação de monitoramento recebe HTTP 413 Content Too Large.
• O erro aparece ao enviar um arquivo grande, formulário, documento JSON, requisição multipart ou outro corpo de requisição.
• Uma versão menor da mesma requisição pode funcionar, enquanto a requisição maior falha.
• A resposta pode vir de um proxy, CDN, WAF, servidor web ou aplicação, e pode ter cabeçalhos ou texto do corpo diferentes dependendo da camada.
• O restante do site pode continuar disponível, e URLs ou tipos de requisição não relacionados podem continuar funcionando.
• A resolução de DNS e o TLS ainda podem estar saudáveis, pois o 413 é uma resposta da camada HTTP.

Causas principais, por probabilidade

1. A requisição excede um limite de upload ou de tamanho do corpo. A aplicação ou o servidor web pode impor um tamanho máximo para o corpo da requisição, arquivo, formulário ou multipart.
2. Um intermediário tem um limite menor. Um reverse proxy, CDN, load balancer ou WAF pode rejeitar a requisição antes que a aplicação de origem a receba.
3. A requisição é encaminhada para um endpoint mais restritivo. URLs, métodos, hosts virtuais ou ambientes diferentes podem ter políticas de tamanho diferentes.
4. Os limites de configuração não estão alinhados. O proxy pode permitir uma requisição que a aplicação rejeita, ou a aplicação pode permitir uma que o proxy bloqueia.
5. A requisição está maior do que o esperado sem intenção. A sobrecarga do multipart, um campo codificado muito grande, um arquivo anexado ou uma nova tentativa do cliente com dados duplicados podem aumentar o tamanho do corpo.
6. O endpoint rejeita conteúdo grande intencionalmente. Algumas APIs ou rotas de upload impõem um limite de produto ou segurança que não deve ser removido sem confirmar a política pretendida.

Como corrigir

Para visitantes e usuários de API

1. Confirme a URL exata e repita a requisição uma vez, sem atualizá-la repetidamente.
2. Se você estiver fazendo upload de um arquivo, tente usar um arquivo menor ou reduza o tamanho dele usando um formato ou método de compressão aprovado.
3. Para uma requisição de API, compare o payload que falha com um payload mínimo válido. Verifique se há campos inesperadamente grandes, dados incorporados, conteúdo duplicado ou uma construção incorreta do multipart.
4. Confirme que a requisição usa o método e o tipo de conteúdo pretendidos. Não remova autenticação nem controles de segurança apenas para contornar o erro.
5. Se requisições menores funcionarem, mas a requisição necessária não, envie ao proprietário do site a URL, o método, o tamanho aproximado da requisição, o horário, os cabeçalhos da resposta e uma descrição sanitizada do payload. Não compartilhe senhas, cookies, tokens ou segredos de API.

Para proprietários de sites e desenvolvedores

1. Capture a requisição que falha. Registre a URL, o método HTTP, o tipo de conteúdo, o tamanho aproximado do corpo, o status, os cabeçalhos da resposta e se a requisição passa por um proxy, CDN, load balancer ou WAF. Remova credenciais e dados pessoais.
2. Reproduza fazendo uma comparação de tamanhos. Teste uma requisição mínima válida e requisições progressivamente maiores, ou compare um upload bem-sucedido com o que falha. Isso ajuda a estabelecer o limite efetivo sem alterar a configuração prematuramente.
3. Identifique a camada que gera a resposta. Compare o corpo da resposta, os cabeçalhos, os logs de acesso, os logs do proxy, os eventos do WAF e os logs da aplicação para o mesmo horário e requisição. Se a requisição não aparecer nos logs da aplicação, um componente upstream pode tê-la rejeitado primeiro.
4. Compare os limites ao longo do caminho. Verifique os limites relevantes do corpo da requisição, de upload, multipart, proxy, CDN, WAF e aplicação. O limite efetivo é controlado pelo primeiro componente que recusa a requisição.
5. Escolha a correção mais restrita. Se a requisição deveria ser aceita, ajuste somente a rota ou o componente relevante depois de confirmar a autorização e as implicações de memória, armazenamento, timeout e segurança. Se o limite for intencional, mantenha-o e altere o fluxo de trabalho do cliente ou documente o máximo compatível.
6. Teste novamente o padrão original da requisição. Use o mesmo método, URL, tipo de conteúdo e tamanho representativo do payload. Confirme que uma requisição aceita chega à aplicação e que requisições malformadas ou claramente grandes demais continuam sendo tratadas conforme o esperado.
7. Verifique os comportamentos adjacentes. Teste uma requisição menor, uma rota não relacionada, o comportamento da autenticação e qualquer outra camada de proxy ou aplicação afetada pela alteração de configuração. Mantenha a alteração sob controle de versão e registre o limite final e o motivo.

Prevenção e como verificar a correção

• Documente os tamanhos máximos compatíveis de requisição, arquivo e multipart para cada rota de upload ou API.
• Mantenha visíveis e, quando possível, sob controle de versão os limites da aplicação, do servidor web, do proxy, da CDN e do WAF.
• Teste tamanhos de limite e requisições grandes representativas em um ambiente que não seja de produção antes da publicação.
• Monitore as respostas 413 por rota, método, cliente e implantação, para distinguir um aumento inesperado de um limite intencional.
• Garanta que os clientes validem o tamanho do arquivo e do payload antes da transmissão e ofereçam uma alternativa clara quando uma requisição for grande demais.
• Mantenha registros suficientes e sanitizados do proxy e da aplicação para determinar qual camada rejeitou uma requisição, sem registrar segredos ou dados pessoais desnecessários.

Perguntas frequentes