HTTP 422 Unprocessable Content: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, serviço de monitoramento ou verificador de sites recebe uma resposta HTTP 422 Unprocessable Content.
• O servidor retorna uma resposta HTTP, portanto a solicitação chegou a um endpoint que fala HTTP; a resolução de DNS e a negociação de TLS ainda podem estar funcionando normalmente.
• A falha afeta uma URL, um método HTTP, um envio de formulário, um payload de API ou uma ação de usuário específicos, e não o site inteiro.
• A resposta pode incluir um corpo de erro que identifica um campo, valor, estado ou regra de validação inválido.
• Os cabeçalhos da resposta podem identificar informações de cache, autenticação, proxy, limitação de taxa, rastreamento da solicitação ou do servidor que ajudam a localizar a origem.

Causas principais, por probabilidade

As causas mais prováveis são:

1. Falha na validação da aplicação. Um campo obrigatório pode estar ausente, um valor pode estar fora do intervalo permitido ou uma combinação de campos válidos individualmente pode não ser aceita para a operação.
2. A solicitação não corresponde ao método ou à representação esperados pela rota. A URL, o método HTTP, o tipo de conteúdo, a estrutura do corpo ou os dados codificados podem não corresponder ao que o endpoint foi projetado para processar.
3. Estado inválido do recurso ou regra de negócio. A solicitação pode ser sintaticamente válida, mas impossível no estado atual, como uma operação que entra em conflito com as regras da aplicação.
4. Regra do servidor, reverse proxy, CDN ou WAF. Um intermediário pode validar ou transformar a solicitação e retornar 422 antes que ela chegue à aplicação.
5. Alterações recentes de roteamento ou deployment. Um schema, serializer, regra de middleware ou integração upstream alterado pode fazer com que solicitações antes aceitas falhem.
6. Contexto de autenticação ou autorização. Esses fatores podem contribuir quando a aplicação valida uma operação autenticada ou o estado da solicitação, mas um 422 simples não deve ser diagnosticado automaticamente como erro de login ou de permissão. Verifique a resposta e os logs para diferenciá-lo de 401 ou 403.

Como corrigir

Se você está visitando o site

1. Tente novamente uma vez e verifique a solicitação. Confira a URL, os valores selecionados no formulário, os dados enviados e todos os campos obrigatórios. Não envie repetidamente a mesma ação se ela puder criar um registro ou acionar um limite.
2. Use o fluxo normal da conta. Se a ação exigir uma conta, faça login pela interface habitual do site e tente novamente. Não cole senhas, cookies ou tokens em solicitações de suporte.
3. Verifique se a falha é específica de uma ação. Se as páginas comuns funcionarem, mas um formulário, upload ou ação de checkout retornar 422, registre essa ação, o horário aproximado e a mensagem de erro exibida.
4. Tente apenas um cliente alternativo apropriado. Se o proprietário do site permitir, uma janela privativa ou outro navegador compatível pode ajudar a diferenciar um problema local de formulário ou sessão de uma resposta do servidor. Não contorne controles de segurança.
5. Entre em contato com o proprietário do site se o problema persistir. Forneça a URL afetada, o tipo de solicitação, se souber, o horário da falha e detalhes do erro sem dados sensíveis. Evite enviar credenciais, cookies de sessão, dados de pagamento ou segredos de API.

Se você é desenvolvedor ou proprietário do site

1. Capture a solicitação e a resposta exatas. Registre o método HTTP, a URL, os parâmetros de consulta, o tipo de conteúdo, os campos relevantes do corpo, o status, o corpo da resposta e os cabeçalhos da resposta. Remova segredos e dados pessoais.
2. Confirme que 422 é a resposta final. Verifique se há redirects, respostas em cache ou um intermediário mascarando a resposta da aplicação. Compare o resultado com uma solicitação conhecida como válida para a mesma rota.
3. Valide a solicitação de acordo com o contrato do endpoint. Verifique campos obrigatórios, tipos de dados, valores permitidos, codificação, tipo de conteúdo, identificadores de recursos e quaisquer requisitos de ordem ou estado. Diferencie a validação semântica de uma sintaxe malformada, que pode produzir outro status.
4. Identifique a camada que gerou a resposta. Use cabeçalhos de resposta característicos, IDs de solicitação, logs de acesso, logs da aplicação, logs do reverse proxy, registros da CDN ou eventos do WAF para determinar se o 422 veio da aplicação ou de um intermediário.
5. Compare uma solicitação com falha e uma bem-sucedida. Altere um detalhe relevante por vez, como o método, o valor de um campo, o tipo de conteúdo, o estado autenticado ou o recurso de destino. Mantenha a reprodução mínima para que a regra de validação real fique visível.
6. Revise as alterações recentes. Verifique deployments, definições de rotas, schemas, serializers, middleware, política de autenticação, regras do proxy, comportamento do cache e integrações upstream próximas do início da falha.
7. Aplique a correção autorizada mais específica possível. Corrija o contrato da solicitação, a regra de validação, a rota ou a configuração do intermediário que explica as evidências. Evite alterações amplas de permissões, segurança, cache ou proxy sem um plano de rollback testado.
8. Teste novamente com segurança e verifique o comportamento relacionado. Repita a mesma solicitação em um ambiente controlado, quando possível, e confirme que métodos e rotas relacionados continuam retornando os status esperados. Se a alteração afetar a produção, siga os procedimentos de gestão de mudanças e aprovação do serviço.

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

• Documente os métodos aceitos, tipos de conteúdo, campos obrigatórios, valores permitidos e respostas de validação esperadas de cada endpoint.
• Valide os dados da solicitação de forma consistente no limite apropriado da aplicação e retorne um corpo de erro acionável, sem dados sensíveis.
• Adicione testes para campos obrigatórios, valores inválidos, conflitos de estado de recursos e solicitações representativas de clientes.
• Monitore as taxas de 422 por rota, método, cliente e deployment para diferenciar uma regressão do tráfego normal de validação.
• Mantenha as configurações de roteamento, schema, proxy, autenticação, CDN e WAF sob controle de versão revisável.
• Preserve IDs de solicitação e logs relevantes por tempo suficiente para correlacionar uma resposta HTTP ao componente que a produziu, removendo segredos e dados sensíveis.
• Teste formulários importantes e métodos de API após releases, alterações de schema e atualizações na configuração de intermediários.

Perguntas frequentes