HTTP 400 Bad Request: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, monitor de disponibilidade, remetente de webhook ou outro cliente HTTP informa 400 Bad Request.
• A resposta pode aparecer apenas para uma URL, um método HTTP, uma query string, um corpo de solicitação, um conjunto de cabeçalhos ou um cliente específico.
• O DNS pode resolver e o TLS pode ser concluído porque o endpoint retornou uma resposta HTTP.
• O corpo da resposta pode mostrar uma página de erro genérica ou uma mensagem de validação mais específica, dependendo do componente que a gerou.
• Os cabeçalhos da resposta podem revelar o status do cache, informações do proxy ou da CDN, contexto de autenticação, redirecionamentos ou identificadores da solicitação.
• Uma solicitação que funcionava anteriormente pode começar a retornar 400 após um deploy ou uma alteração nas regras de roteamento, validação, proxy ou segurança.

Causas principais, por probabilidade

1. Detalhes da solicitação malformados ou inválidos: A URL, a query string, os cabeçalhos, os cookies, o método ou o corpo da solicitação podem não atender ao formato esperado pelo endpoint.
2. Regras de validação ou roteamento da aplicação: A aplicação pode rejeitar parâmetros ausentes, com tipo incorreto, não compatíveis ou inconsistentes, ou a solicitação pode ter como destino uma rota que não aceita esse método.
3. Tratamento pelo servidor web, reverse proxy, CDN ou WAF: Um intermediário pode rejeitar a solicitação antes que ela chegue à aplicação devido a regras de análise, roteamento, filtragem ou políticas.
4. Limites de tamanho ou formato da solicitação: Um corpo, conjunto de cabeçalhos, URL, coleção de cookies ou valor enviado pode exceder um limite específico do ambiente ou usar um formato não compatível.
5. Estado relacionado à autenticação ou à sessão: Uma aplicação pode usar 400 para um token inválido, dados de sessão malformados ou uma solicitação que não pode ser associada ao estado esperado. Outros sistemas usam 401 ou 403 para problemas de acesso relacionados, portanto confirme o comportamento nos logs relevantes.
6. Alterações recentes de configuração ou deploy: Rotas, lógica de validação, autenticação, cache, proxy, CDN ou configurações de segurança atualizadas podem mudar a forma como uma solicitação conhecida é processada.

Como corrigir

Se você é visitante ou consumidor de API

1. Tente novamente a URL exata uma vez e verifique erros de digitação, espaços não intencionais, parâmetros de consulta truncados ou um favorito desatualizado.
2. Se a solicitação exigir uma conta, faça login pelo processo normal do site e tente novamente. Não cole senhas, cookies ou tokens em solicitações de suporte.
3. Se estiver usando um cliente de API, compare o método HTTP, os parâmetros obrigatórios, os cabeçalhos, o content type e o corpo da solicitação com os requisitos documentados do endpoint.
4. Se uma solicitação no navegador falhar, tente a mesma ação sem atualizar a página repetidamente. Solicitações repetidas podem aumentar a carga ou interagir com limites de taxa.
5. Registre a URL ou o endpoint, o método, o horário aproximado, o status da resposta e qualquer ID de solicitação exibido na resposta. Compartilhe apenas detalhes sanitizados com o proprietário do site.
6. Se o erro afetar apenas uma ação, informe essa ação e o comportamento esperado. Se muitas páginas não relacionadas falharem, informe o escopo mais amplo em vez de presumir que todas as falhas têm a mesma causa.

Se você é proprietário ou desenvolvedor do site

1. Capture uma reprodução mínima. Registre o método HTTP, a URL completa com valores confidenciais removidos, o status, os cabeçalhos da resposta, os cabeçalhos relevantes da solicitação, o content type e um corpo da solicitação minimizado com segurança. Confirme que o 400 é a resposta final, e não uma resposta intermediária seguida de um redirecionamento.
2. Compare uma solicitação funcional com uma que falha. Verifique a rota, o método, os parâmetros de consulta, o formato do corpo, o content type, os cookies, o estado de autenticação, o cliente e o tamanho do payload. Altere uma variável relevante por vez.
3. Identifique a camada que respondeu. Use os cabeçalhos da resposta, o texto do corpo, os IDs de solicitação e os registros de data e hora para determinar se a resposta foi produzida pela aplicação, pelo servidor web, pelo reverse proxy, pela CDN ou pelo WAF. Os nomes e valores dos cabeçalhos variam conforme o ambiente; trate-os como indícios, não como prova.
4. Examine os logs correspondentes. Pesquise na camada identificada e nos componentes adjacentes usando o mesmo horário, rota, método e identificador da solicitação. Procure erros de análise, falhas de validação, métodos rejeitados, violações de limite, incompatibilidades de roteamento ou correspondências com regras de segurança.
5. Revise as alterações recentes. Compare deploys e alterações de configuração que afetem roteamento, análise de solicitações, autenticação, cache, encaminhamento pelo proxy, comportamento da CDN e regras do WAF. Verifique se a rota deve aceitar a solicitação que está falhando.
6. Aplique a correção segura mais específica possível. Corrija o contrato da solicitação ou a rota ou regra específica que está rejeitando tráfego válido. Evite alterações amplas de segurança, permissões, limites de tamanho ou proxy sem autorização e testes.
7. Teste novamente e verifique o comportamento adjacente. Repita a solicitação original e, em seguida, teste o método esperado, uma solicitação inválida representativa e as rotas relacionadas. Confirme que a correção não transforma solicitações malformadas em sucessos indesejados nem quebra redirecionamentos, autenticação, cache ou controles de segurança.
8. Preserve evidências úteis. Mantenha detalhes sanitizados da solicitação, registros de data e hora, cabeçalhos relevantes e logs de acordo com suas práticas normais de retenção e privacidade.

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

• Defina e documente os métodos, parâmetros, content types, requisitos de autenticação e limites de tamanho de solicitação aceitos pelas rotas importantes.
• Valide as solicitações de forma consistente e retorne uma mensagem de erro útil e não sensível quando apropriado.
• Mantenha as configurações de roteamento, proxy, CDN, autenticação, cache e WAF sob controle de alterações.
• Teste solicitações válidas e inválidas representativas após releases da aplicação ou da infraestrutura.
• Monitore as taxas de 400 por rota, método, cliente e deploy para distinguir uma regressão localizada de uma alteração ampla.
• Retenha identificadores de solicitação e logs relevantes por tempo suficiente para relacionar uma resposta ao componente que a produziu.
• Remova ou mascare senhas, cookies, valores de autorização, dados pessoais e segredos de API dos logs e das evidências de suporte.

Perguntas frequentes