Erro 413 Content Too Large: como corrigir limite de upload no proxy e na aplicação

O erro 413 Content Too Large indica que o servidor recusou o conteúdo da requisição por exceder o limite aceito. Em arquiteturas modernas, CDN, proxy reverso, servidor web, framework e código podem impor tamanhos diferentes. Aumentar apenas uma configuração pode trocar 413 por timeout, falta de memória ou disco cheio.

Este guia mostra como localizar a camada que respondeu, medir o corpo enviado, alinhar limites, processar uploads por streaming, validar antes de armazenar e testar sem enviar arquivos sensíveis.

Legenda: o menor limite efetivo da cadeia decide se o corpo chega à aplicação.

O que o status 413 significa

A RFC 9110 define 413 quando o conteúdo é maior do que o servidor deseja ou consegue processar. A resposta pode incluir Retry-After quando a condição for temporária, mas repetir o mesmo arquivo imediatamente raramente resolve um limite fixo.

413 é diferente de 414, relacionado à URI, e de 431, relacionado aos cabeçalhos. Também não é 507 ou falta de espaço: o servidor pode rejeitar preventivamente antes de gravar qualquer byte.

Capture resposta, cabeçalhos e origem

curl -v -F "arquivo=@amostra.bin" https://exemplo.test/upload

Use arquivo fictício. O modo verboso pode mostrar cabeçalhos da CDN ou proxy. Preserve status, Server, identificador de requisição e horário, removendo cookies e tokens.

Se a aplicação não registra a requisição, a rejeição ocorreu antes dela. Se registra começo mas não o controlador, um middleware pode ter bloqueado. Correlacione logs por ID.

Crie arquivos de teste sem dados reais

Python:

from pathlib import Path

def criar_amostra(caminho, megabytes):
    bloco = b"0" * (1024 * 1024)
    with Path(caminho).open("wb") as f:
        for _ in range(megabytes):
            f.write(bloco)

criar_amostra("amostra-5mb.bin", 5)

Gere tamanhos abaixo, igual e acima do limite esperado, como 4, 5 e 6 MB. Defina se “MB” no requisito significa decimal ou MiB; configurações podem usar unidades diferentes.

Content-Length e transferência em partes

Quando o cliente envia Content-Length, a borda pode rejeitar antes de ler o corpo. Em transferência chunked, o servidor precisa contar enquanto recebe. Não dependa apenas do cabeçalho fornecido pelo cliente; ele pode estar ausente ou incorreto.

No cliente web, o tamanho de File ajuda a impedir envio inútil:

const LIMITE = 5 * 1024 * 1024;
if (arquivo.size > LIMITE) {
  throw new Error("O arquivo ultrapassa 5 MiB");
}

Essa validação melhora experiência, mas o servidor continua sendo autoridade.

Descubra a camada responsável

Teste a aplicação diretamente somente em rede controlada. Se origem aceita e domínio público rejeita, o limite está na borda. Se ambas rejeitam, examine servidor e framework.

Mapeie:

Camada	Evidência	Configuração típica
CDN/WAF	ID e página próprios	plano ou regra de upload
proxy	log sem entrada na app	limite de corpo
framework	exceção de middleware	parser multipart
aplicação	mensagem de negócio	política por tipo

Não exponha a origem à internet para testar. Use acesso interno autorizado.

Nginx e client_max_body_size

No Nginx, client_max_body_size controla o tamanho permitido do corpo no contexto http, server ou location. Exemplo:

server {
    client_max_body_size 10m;

    location /upload {
        proxy_pass http://app;
    }
}

Valide antes de recarregar:

nginx -t

Use o procedimento administrativo do ambiente. Um valor global enorme aumenta exposição de rotas que nunca deveriam receber arquivos. Prefira escopo específico.

Framework e parser multipart

Mesmo após o proxy aceitar, o framework pode limitar corpo, campo ou arquivo. Verifique documentação da versão usada. Parsers podem carregar tudo em memória ou mover para temporário após um limiar.

Valide separadamente:

• tamanho total da requisição;
• tamanho de cada arquivo;
• quantidade de partes;
• tamanho de campos de texto;
• tempo total;
• tipo permitido.

Muitos arquivos pequenos também podem consumir recursos. Limite quantidade e nomes, não apenas bytes.

Streaming evita carregar tudo na memória

Um antipadrão:

dados = upload.read()  # corpo inteiro em RAM
processar(dados)

Prefira blocos e teto contado:

def copiar_limitado(origem, destino, limite, bloco=1024 * 1024):
    total = 0
    while parte := origem.read(bloco):
        total += len(parte)
        if total > limite:
            raise ValueError("upload excedeu o limite")
        destino.write(parte)
    return total

O arquivo parcial deve ser temporário e removido em falha. Não disponibilize antes de validação e confirmação.

Legenda: os blocos são contados e validados antes de o arquivo ganhar destino definitivo.

Tipo MIME, extensão e conteúdo

Extensão e Content-Type são declarações do cliente. Confirme formatos permitidos por assinatura e parser apropriado. Não execute arquivos enviados nem confie no nome para construir caminhos.

Gere nome interno aleatório, mantenha nome original apenas como metadado sanitizado e impeça ../ ou separadores. Armazene fora da raiz pública quando possível.

Se houver antivírus ou análise, mantenha o item em quarentena até aprovação. Tamanho permitido não significa conteúdo seguro.

Espaço em disco e diretório temporário

Uploads podem ocupar temporário e destino ao mesmo tempo. Monitore espaço e inodes. Se múltiplas instâncias usam disco efêmero, o arquivo pode desaparecer depois da resposta.

Defina limpeza para uploads abandonados com idade e estado conhecidos. Nunca execute remoção ampla por padrão de nome sem restringir a pasta controlada.

Ao falhar por espaço, devolva status e mensagem coerentes; não transforme tudo em 413.

Timeout, velocidade e conexões lentas

Um limite maior exige tempo maior para clientes lentos, mas elevar todos os timeouts pode prender recursos. Defina timeout de cabeçalho, leitura, processamento e resposta separadamente quando a pilha permite.

Calcule expectativa: 100 MB em conexão de 10 Mbps exige mais de 80 segundos sem contar overhead. Para arquivos realmente grandes, considere upload direto a armazenamento por URL curta, multipart e retomada.

Upload direto e URLs assinadas

O backend autoriza tipo, tamanho e usuário e emite URL temporária para armazenamento. O cliente envia bytes diretamente; depois o backend confirma metadados.

cliente → pede autorização → backend
cliente → envia arquivo → armazenamento
backend → valida evento/metadados → confirma

A URL deve expirar, limitar operação e evitar permissão de leitura pública. O backend não deve confiar apenas no evento do cliente.

Mensagem útil para o usuário

Evite “falha no upload”. Informe limite e tamanho detectado:

{
  "error": "UPLOAD_TOO_LARGE",
  "message": "O arquivo excede o limite de 5 MiB.",
  "maxBytes": 5242880
}

Não recomende compactação se o formato não aceitar ou se a compressão prejudicar o caso. Ofereça divisão apenas quando o sistema consegue recompor ou processar partes.

Observabilidade e capacidade

Registre rota, tamanho, camada, status e tempo, sem nome pessoal ou conteúdo. Métricas úteis: distribuição de tamanhos, proporção de 413, temporários abandonados, duração e memória.

Se muitos usuários ficam pouco acima do limite, o produto pode estar desalinhado. Se poucos tentam volumes extremos, o limite está protegendo o serviço. Decida com dados.

Testes automatizados de fronteira

Teste limite - 1, limite e limite + 1. Confirme que rejeição não deixa arquivo parcial e que a resposta mantém formato consistente.

def permitido(tamanho, limite=5 * 1024 * 1024):
    return tamanho <= limite

assert permitido(5 * 1024 * 1024)
assert not permitido(5 * 1024 * 1024 + 1)

Inclua múltiplas partes, Content-Length ausente, cancelamento e nome estranho. Faça isso em ambiente autorizado.

Plano de correção por etapas

1. capture quem respondeu 413;
2. confirme tamanho real;
3. liste limites de todas as camadas;
4. defina política de produto;
5. alinhe proxy, framework e aplicação;
6. implemente streaming e temporário;
7. teste fronteiras e limpeza;
8. monitore após a mudança.

Use o criador de fluxogramas, as ferramentas e o iatnGrid para documentar cenários e resultados.

Checklist final

Antes de aumentar o limite, estime o pior caso concorrente. Vinte uploads de 100 MiB podem ocupar gigabytes entre trânsito, temporário e destino. Se o parser mantém o corpo em memória, o consumo cresce mais. Faça teste gradual com métricas e limite de concorrência.

Políticas devem variar por rota. Uma foto de perfil pode aceitar 5 MiB, enquanto uma importação administrativa aceita 100 MiB. Separar regras reduz a superfície e melhora mensagens. Não aplique o maior valor globalmente.

Em sistemas com várias instâncias, confirme que todas receberam a configuração. Se apenas algumas mudaram, o usuário alternará entre sucesso e 413. Registre versão da configuração e instância nos logs internos.

Uploads retomáveis dividem o arquivo, mas ainda exigem limite acumulado, ordem, duplicação, expiração e confirmação. Limitar cada parte sem controlar o total permite ultrapassar a política. Associe a sessão ao usuário autorizado e use identificador opaco.

Arquivos compactados exigem limite de expansão e quantidade de entradas. Um corpo pequeno pode gerar saída grande e processamento demorado. Verifique tipo e complexidade antes de disponibilizar o resultado.

O cancelamento do cliente deve interromper leitura e limpar o temporário. Confirme como proxy e framework propagam desconexões; caso contrário, o servidor pode continuar processando bytes que ninguém espera.

Depois da mudança, compare tamanho, memória, disco, duração e falhas. Se o uso real se aproxima do teto, adote arquitetura própria para arquivos grandes em vez de aumentar indefinidamente.

Documente o valor em bytes, a unidade exibida, onde cada camada é configurada, responsável e teste de fronteira. Isso evita documentação dizendo 10 MB enquanto o proxy aplica 8 MiB.

Teste simultaneidade, muitas partes pequenas, campo textual enorme, nome incomum, cancelamento e espaço temporário insuficiente. Cada falha deve deixar o sistema consistente e devolver um código que represente a causa real.

Uma revisão de segurança deve confirmar autenticação antes de reservar recursos, taxa por usuário, armazenamento fora da raiz pública, quarentena e expiração. Aumentar o limite sem controles transforma uma correção funcional em risco operacional.

Faça também um ensaio de reversão. A equipe precisa saber restaurar o limite anterior e limpar sessões incompletas caso a mudança aumente memória, disco ou latência além do aceitável.

Confirme o resultado novamente após reiniciar proxy e aplicação, garantindo que a configuração persistiu em todas as instâncias.

Em APIs públicas, publique o limite na documentação e, quando possível, em metadados da interface. O cliente pode bloquear cedo e orientar o usuário, mas não deve assumir que o valor jamais muda. A resposta do servidor continua definitiva.

Se o upload passa por formulário multipart, considere o overhead de limites e partes. Um arquivo exatamente no teto pode produzir requisição total um pouco maior. Defina claramente se o limite é por arquivo ou pelo corpo completo e teste ambos.

Compressão HTTP da requisição não deve ser aceita como forma de burlar o limite. O servidor precisa considerar o tamanho expandido e capacidade de processamento. Para formatos já comprimidos, como JPEG e ZIP, compressão adicional traz pouco benefício.

Em filas assíncronas, responda somente depois de persistir o arquivo com integridade suficiente para continuar. Gere hash durante o streaming quando necessário e compare com metadado confiável. Um status de aceitação não deve ser emitido se o temporário pode desaparecer antes do consumidor.

Defina retenção para uploads rejeitados, incompletos e concluídos. Itens rejeitados por tamanho normalmente devem ser removidos imediatamente; registros de auditoria podem manter somente tamanho, categoria e identificador, nunca conteúdo.

Ao usar armazenamento direto, limite também o tamanho no próprio serviço de objetos e valide no evento de conclusão. Se o cliente envia mais que o autorizado, remova o objeto e marque a sessão inválida. Não confie no tamanho declarado durante a autorização.

Teste falhas de rede no meio do envio e reinício da aplicação. O sistema deve recuperar ou expirar a sessão, liberar espaço e permitir nova tentativa sem duplicar registros. Esses cenários diferenciam um limite bem projetado de uma simples alteração no proxy.

• a camada que respondeu 413 foi identificada;
• tamanho e unidade foram confirmados;
• limites estão alinhados e restritos à rota;
• cliente valida para experiência, servidor para segurança;
• streaming evita carregar tudo em memória;
• temporários são limpos em falha;
• tipo, nome e conteúdo são validados;
• disco, timeout e concorrência foram dimensionados;
• mensagens informam limite sem expor detalhes;
• testes cobrem as fronteiras;
• observabilidade não registra conteúdo;
• nenhuma origem foi exposta para depuração.

Documentação primária

• RFC 9110 — 413 Content Too Large
• Nginx — client_max_body_size
• MDN — FormData
• Python — arquivos temporários
• OWASP — File Upload Cheat Sheet

Nota de produção

Rascunho autoral orientado à busca “erro 413 Content Too Large como resolver”. Os exemplos usam arquivos fictícios e limites explícitos. A revisão humana deve confirmar a infraestrutura real, testar as fronteiras e revisar os links antes da publicação.

Camada extra: como tomar uma decisão melhor neste cenário

Em uso real, Erro 413 Content Too Large: como corrigir limite de upload no proxy e na aplicação costuma envolver mais de uma camada. O ganho de qualidade aparece quando cada camada tem uma pergunta de verificação antes de qualquer mudança definitiva.

O erro **413 Content Too Large** indica que o servidor recusou o conteúdo da requisição por exceder o limite aceito. Em arquiteturas modernas, CDN, proxy reverso, servidor web, framework e código podem impor tamanhos diferentes. Aumentar ap A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Separe exposição, probabilidade e impacto

Em segurança e privacidade, um alerta isolado não mede o risco inteiro. Para HTTP, 413, upload, Nginx, registre primeiro o que está exposto: conta, arquivo, dispositivo, sessão, metadado ou autorização. Depois avalie como o abuso poderia acontecer e o que seria perdido se acontecesse. Essa separação ajuda a priorizar uma credencial comprometida acima de um aviso meramente visual e, ao mesmo tempo, evita transformar qualquer comportamento incomum em prova de ataque.

Prefira respostas reversíveis no primeiro minuto: interromper uma transação, revogar uma sessão, remover uma permissão, confirmar a identidade por outro canal ou trabalhar em uma cópia. Só depois faça mudanças permanentes. O objetivo não é reagir com medo, mas reduzir a janela de exposição enquanto você coleta evidências.

Mini matriz de decisão

Sinal	O que verificar	Ação inicial
Pedido inesperado ou comportamento fora do padrão	Identidade, domínio, origem e contexto	Não confirmar pela mesma mensagem
Permissão ou acesso excessivo	Necessidade real e escopo	Reduzir ao mínimo necessário
Dado sensível envolvido	Onde será processado e armazenado	Preferir fluxo local ou serviço confiável

O teste que evita falsa sensação de segurança

Depois da correção, repita o cenário original de forma controlada. Verifique se a conta continua funcional, se a permissão removida não reapareceu, se o arquivo não contém a informação que deveria ter sido removida e se o canal alternativo de confirmação realmente funciona. Segurança sem teste de recuperação é apenas configuração; a validação transforma a configuração em controle.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.