Erros de cliente HTTP 4xx: significado, diagnóstico e correções

O que este erro significa e como reconhecê-lo

Um navegador, cliente de API ou solicitação automatizada recebe um status HTTP entre 400 e 499. A resposta pode conter uma página de erro curta, um objeto de erro JSON, cabeçalhos explicativos ou nenhum corpo útil.

As respostas visíveis comuns incluem:

• 400 Bad Request: O servidor não consegue processar a solicitação conforme recebida.
• 401 Unauthorized: A autenticação está ausente, é inválida ou é necessária para o recurso.
• 403 Forbidden: A solicitação foi entendida, mas o acesso não é permitido.
• 404 Not Found: O recurso ou a rota solicitada não foi encontrada.
• 405 Method Not Allowed: O recurso não oferece suporte ao método HTTP utilizado.
• 409 Conflict: A solicitação entra em conflito com o estado atual do recurso.
• 410 Gone: O recurso não está mais disponível de propósito.
• 413 Content Too Large: O corpo da solicitação excede um limite configurado ou documentado.
• 429 Too Many Requests: O cliente excedeu um limite de taxa ou de cota.

O mesmo status pode apresentar comportamentos diferentes dependendo de ter sido gerado pela aplicação, por um reverse proxy, pela CDN ou pelo firewall de aplicação web.

Causas principais, por probabilidade

Causas comuns, em ordem de diagnóstico

1. Solicitação malformada ou inválida — 400: Sintaxe inválida, URL codificada incorretamente, JSON inválido, tipo de conteúdo incorreto ou dados obrigatórios ausentes podem impedir o processamento.
2. Autenticação ausente ou inválida — 401: A solicitação pode não conter credenciais, conter uma credencial expirada ou usar credenciais que o endpoint não aceita.
3. Permissão insuficiente ou política de segurança — 403: A identidade pode estar autenticada, mas não autorizada; ou uma regra de IP, CDN, WAF, proxy ou política da aplicação pode negar o acesso.
4. Rota ou estado do recurso incorreto — 404 ou 410: A URL pode estar errada, uma implantação pode não conter a rota, um recurso pode ter sido movido ou o proprietário pode tê-lo removido deliberadamente.
5. Método HTTP não compatível — 405: O cliente usou GET, POST, PUT, PATCH ou DELETE quando o contrato do endpoint permite um método diferente.
6. Conflito de estado ou versão — 409: A alteração solicitada pode entrar em conflito com o estado atual do recurso, com um objeto existente ou com outra atualização.
7. Solicitação excede um limite — 413: O corpo, o upload ou a solicitação codificada é maior que um limite aplicado pela aplicação ou por um intermediário.
8. Solicitações em excesso — 429: O cliente excedeu um limite de taxa, de concorrência ou uma cota.

Uma CDN, um WAF ou um reverse proxy pode produzir uma resposta 4xx antes que a solicitação chegue à origem. Nesse caso, o erro aparente da aplicação pode pertencer a uma camada de rede anterior.

Como corrigir

1. Capture a resposta exata

Registre o status numérico, a URL completa, o método HTTP, o timestamp, o tipo de solicitação e os cabeçalhos de resposta relevantes. Para solicitações de API, registre também o tipo de conteúdo sanitizado, o tamanho da solicitação e qualquer ID de correlação ou de solicitação. Não registre nem compartilhe senhas, chaves de API, cookies ou tokens de acesso.

Compare a resposta com uma solicitação conhecida como válida, quando houver uma. Verifique se o corpo e os cabeçalhos da resposta identificam a aplicação de origem, o proxy, a CDN ou o WAF.

2. Verifique o contrato da solicitação

Para 400, valide a codificação da URL, os parâmetros obrigatórios, a sintaxe de JSON ou formulário, o tipo de conteúdo e os campos obrigatórios. Confirme que o cliente está enviando o formato documentado pelo endpoint, em vez de alterar as configurações do servidor.

Para 405, verifique os métodos permitidos pelo endpoint e certifique-se de que o cliente não está seguindo um redirecionamento nem usando uma URL voltada para navegador em uma operação de API. Verifique o cabeçalho de resposta Allow quando fornecido.

Para 409, inspecione o estado atual do recurso. O objeto pode já existir, ter sido alterado desde a leitura ou estar indisponível para a transição solicitada. Siga o comportamento de conflito ou versionamento da aplicação, em vez de repetir a gravação sem critério.

3. Verifique a identidade e o acesso

Para 401, confirme que a autenticação está presente, atualizada e sendo enviada no formato exigido pelo endpoint. Obtenha uma credencial nova pelo processo aprovado se ela tiver expirado. Nunca cole credenciais em tickets, logs ou comandos de diagnóstico.

Para 403, confirme que a identidade autenticada tem a função ou permissão necessária para o recurso. Proprietários de sites devem inspecionar regras de autorização, restrições de IP, políticas do WAF ou da CDN e controles de acesso específicos do ambiente. Um 403 não é corrigido alterando a URL, a menos que a própria URL tenha causado a correspondência com uma política.

4. Verifique o roteamento e o estado do recurso

Para 404, verifique a ortografia, o uso de maiúsculas e minúsculas quando relevante, os prefixos do caminho, o nome do host, o ambiente de implantação e o comportamento do caminho final. Verifique o roteamento da aplicação, o encaminhamento do reverse proxy e se o recurso realmente existe.

Para 410, trate a resposta como um sinal de remoção intencional, a menos que o proprietário confirme o contrário. Atualize links ou clientes para o recurso substituto, se houver; não simplesmente repita a mesma URL.

5. Verifique o tamanho da solicitação

Para 413, meça o corpo da solicitação ou o upload e compare-o com os limites documentados. Verifique cada camada relevante — cliente, reverse proxy, CDN/WAF e aplicação — porque o menor limite pode gerar a resposta. Primeiro, reduza o payload ou use o mecanismo de upload documentado.

Aumentar um limite exige autorização, análise de capacidade e alterações de configuração coordenadas. Isso pode aumentar o consumo de recursos e a exposição ao abuso por meio de solicitações grandes.

6. Lide com a limitação de taxa com segurança

Para 429, interrompa as repetições desnecessárias, reduza a concorrência e a frequência das solicitações e respeite Retry-After quando presente. Use exponential backoff limitado e cache no cliente quando apropriado.

Proprietários de sites devem identificar o escopo do limite — usuário, token, IP, rota ou serviço — e analisar a configuração da cota e os padrões de tráfego antes de alterá-lo.

7. Identifique a camada que respondeu

Proprietários de sites devem correlacionar o timestamp, o caminho, o método e o ID da solicitação com os logs da aplicação, do reverse proxy, da CDN e de segurança. Se não houver uma solicitação correspondente na origem, investigue primeiro a CDN, o WAF ou o proxy.

Compare os cabeçalhos da resposta, o formato do corpo e os identificadores do servidor entre um teste aprovado diretamente na origem e o caminho público. Não contorne os controles de segurança sem autorização.

8. Teste novamente a alteração específica

Faça um novo teste somente depois de alterar a solicitação ou a regra responsável pela resposta. Confirme tanto o caso de sucesso esperado quanto os casos de falha relevantes, como uma identidade não autorizada, um payload grande demais ou uma solicitação enviada com frequência excessiva. Monitore as tendências de 4xx após implantações ou alterações de políticas para detectar regressões.

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

• Documente os métodos dos endpoints, os campos obrigatórios, os requisitos de autenticação, os códigos de resposta, os limites de tamanho das solicitações e o comportamento da limitação de taxa.
• Mantenha os links internos e externos atualizados e teste redirecionamentos ou remoções quando as rotas mudarem.
• Use testes automatizados para limites de autorização, métodos compatíveis, entradas malformadas e conflitos de estado dos recursos.
• Valide os tamanhos das solicitações e o comportamento de repetição dos clientes antes da liberação em produção.
• Use backoff limitado, cache e deduplicação de solicitações para clientes que possam receber respostas 429.
• Monitore as taxas de 4xx por rota, status, cliente e camada responsiva, para diferenciar links quebrados, regressões de permissão e alterações no cliente.
• Mantenha IDs de correlação e logs sanitizados disponíveis nas camadas da aplicação, do proxy, da CDN e de segurança.

Perguntas frequentes