422 Unprocessable Entity: o que significa e como corrigir

O que significa 422 Unprocessable Entity

O 422 teve origem no WebDAV (RFC 4918) e depois foi amplamente adotado por APIs REST como a resposta padrão para falhas de validação semântica. A RFC 9110 renomeou formalmente o texto do status para 422 Unprocessable Content, descartando a redação "Entity" específica do WebDAV, embora os dois nomes descrevam o mesmo código de status e "Unprocessable Entity" continue sendo o rótulo bem mais comum nos padrões de frameworks e na documentação de APIs. A distinção que importa é sintaxe versus semântica: o JSON foi interpretado corretamente, todo campo obrigatório bate com o tipo esperado, e a requisição está bem formada por toda regra estrutural, mas um valor dentro dela viola uma regra de negócio, como um endereço de e-mail no formato errado, uma data no passado onde uma data futura é exigida, ou um campo que referencia um registro que não existe.

Como o erro aparece

Um 422 quase nunca aparece como um erro de navegação de navegador, já que ele é majoritariamente uma resposta de API em vez de algo que um link ou envio de formulário dispara diretamente; aparece em uma aba de rede, em um aviso de erro, ou em uma asserção de teste que falhou. Na linha de comando, o corpo da resposta é onde está o detalhe útil:

curl -i -X POST https://api.example.com/v1/users   -H "Content-Type: application/json"   -d '{"email": "not-an-email", "age": -5}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errors": {"email": ["is not a valid email"], "age": ["must be greater than 0"]}}

A maioria das APIs bem construídas devolve um corpo de erro estruturado junto com o 422, nomeando exatamente qual campo falhou e por quê, em vez de deixar quem chamou adivinhar só pelo código de status.

O que causa um 422 Unprocessable Entity

• Erros de validação em APIs REST. Aplicações Rails comumente devolvem 422 automaticamente quando um modelo ActiveRecord falha na validação ao criar ou atualizar. A validação de form request do Laravel devolve 422 por padrão para regras que falharam. O FastAPI, construído sobre o Pydantic, devolve 422 sempre que os dados de uma requisição falham nas checagens de tipo ou de restrição de um modelo Pydantic, motivo pelo qual esse é um dos códigos de status mais vistos especificamente em projetos FastAPI.
• Um campo com o tipo certo mas um valor inválido. Uma string onde uma string era esperada, mas uma que falha em uma checagem de formato, um limite de tamanho, ou uma lista de valores permitidos.
• Uma referência a algo que não existe. Uma chave estrangeira, um id de usuário, ou um slug no corpo da requisição que está sintaticamente correto mas não corresponde a nenhum registro real.
• Regras de negócio além da validação simples de campo. Um código de desconto que é sintaticamente válido mas expirado, ou uma quantidade que é um inteiro válido mas excede o estoque disponível.
• Falta de um campo obrigatório inteiramente. Dependendo do framework, um campo obrigatório ausente pode devolver 422 em vez de 400, já que a requisição é interpretada sem problema, só falta um valor que a camada de validação exige.

422 contra 400

A linha é sintaxe versus semântica. 400 Bad Request significa que o servidor não conseguiu interpretar a requisição de jeito nenhum, por exemplo JSON malformado ou um corpo que não é válido por nenhuma regra estrutural. 422 significa que a requisição foi interpretada sem nenhum problema, e todo campo tem o tipo certo, mas um valor dentro dela falha em uma regra que a aplicação confere depois de interpretar. Na prática muitas APIs confundem essa distinção e usam 400 para os dois casos, o que é defensável mas menos preciso; um cliente integrando com uma API deveria ler o corpo da resposta em vez de confiar só no código de status para saber exatamente o que falhou.

Como corrigir um erro 422

Se você é um cliente chamando uma API

1. Leia o corpo da resposta, não só o código de status. O 422 de uma API bem construída nomeia o campo específico e a regra que falhou, o que diz exatamente o que corrigir sem mais adivinhação.
2. Confira o campo contra as restrições documentadas da API, como formato, tamanho e valores permitidos, já que essas são regras de negócio que o schema sozinho não vai mostrar.
3. Trate o 422 como um sinal para corrigir os dados, não para tentar de novo a requisição sem mudar nada. Tentar de novo uma requisição idêntica que falhou na validação vai falhar de forma idêntica toda vez; um cliente bem comportado deveria mostrar o erro específico para o usuário em vez de tentar de novo silenciosamente.

Se você administra a API

1. Sempre devolva um corpo de erro estruturado junto com o 422, nomeando o campo e a regra que falhou, em vez de um código de status isolado sem explicação nenhuma.
2. Mantenha as mensagens de erro de validação específicas e acionáveis, por exemplo "email precisa ser um endereço válido" em vez de um genérico "validação falhou" que força quem chamou a adivinhar qual campo, entre vários, era o problema.
3. Decida deliberadamente entre 400 e 422 para a sua API e documente a escolha, para que integradores consigam construir um tratamento de erro confiável em vez de tratar todo 4xx da mesma forma.
4. Registre os payloads validados-mas-rejeitados durante o desenvolvimento para pegar casos em que o seu próprio código de cliente está enviando dados que consistentemente falham na validação, o que geralmente aponta para uma diferença entre o cliente e as regras reais da API.

Como um cliente deveria tratar uma resposta 422

Um cliente bem projetado trata o 422 como fundamentalmente diferente de um erro 5xx ou uma falha de rede: significa que o servidor está saudável e funcionando corretamente, e quem chamou enviou algo que o servidor nunca vai aceitar do jeito que está. A resposta certa é interpretar o corpo do erro, mapear cada campo que falhou de volta para o formulário ou o input que o produziu, e mostrar ao usuário algo acionável, não tentar de novo com backoff da forma que você faria para um timeout ou um 503. Testes automatizados que exercitam a camada de validação de uma API deveriam fazer asserção sobre o corpo de erro específico devolvido, não só o código de status 422, já que isso é o que confirma que a própria lógica de validação está correta.

Como prevenir que 422 passem despercebidos

Uma regra de validação que mudou inesperadamente, seja por um deploy, uma atualização de biblioteca de terceiros, ou uma migração de schema, pode começar a rejeitar requisições que costumavam ter sucesso sem que ninguém perceba. Uma verificação HTTP que envia um payload conhecido como válido e faz asserção no código de status esperado pega esse tipo de regressão imediatamente depois do deploy que a causou. Para APIs com mais de um endpoint ou um payload que o código de status sozinho não consegue verificar totalmente, monitoramento de API que também confere o corpo da resposta confirma a própria lógica de validação, não só que o servidor está alcançável.

Erros relacionados

Veja 400 Bad Request para o caso de requisição-não-interpretável contra o qual este guia contrasta, a visão geral dos 4xx para a família mais ampla, e 401 Unauthorized e 405 Method Not Allowed em outros pontos deste lote.

Perguntas frequentes

422 Unprocessable Entity é o mesmo que 422 Unprocessable Content?

Sim. A RFC 9110 renomeou a frase de razão para Unprocessable Content, mas é o mesmo código de status com o mesmo significado; a maioria dos frameworks e documentações de API ainda usa a redação mais antiga Unprocessable Entity.

Por que a minha aplicação FastAPI devolve 422 para um campo ausente?

O FastAPI valida os dados da requisição automaticamente contra os seus modelos Pydantic, e um campo obrigatório ausente, ou com o tipo errado, falha nessa validação e devolve 422 com um corpo descrevendo exatamente qual campo e qual regra falharam.

Devo tentar de novo uma requisição que recebeu um 422?

Só depois de mudar os dados que falharam na validação. Tentar de novo a requisição idêntica vai produzir o mesmo 422 toda vez, já que o servidor está rejeitando correta e consistentemente o mesmo input inválido.

Qual é a diferença entre 422 e 400 na prática?

O 400 é para uma requisição que o servidor não consegue interpretar de jeito nenhum. O 422 é para uma requisição que é interpretada sem problema mas contém um valor que falha em uma regra de validação ou de negócio. Muitas APIs do mundo real usam 400 para os dois casos, então sempre confira a convenção documentada da API específica que você está chamando.

Um 422 pode significar que o servidor tem um bug?

Pode, se a própria regra de validação estiver errada, por exemplo rejeitando um formato de e-mail genuinamente válido. Mas um 422 por design significa que o servidor está funcionando como pretendido e objetando aos dados, então investigue a regra de validação real antes de assumir que está quebrado.