Como usar corretamente os códigos de status HTTP: a primeira bifurcação do cliente

O que é

A RFC 9110 define as cinco classes e cada um dos códigos; um cliente deve reconhecer a classe pelo primeiro dígito e tratar um código desconhecido como o código x00 da sua classe. Na prática, algumas distinções são decisivas: 401 significa credenciais ausentes ou inválidas, e o servidor deve enviar nesse caso um cabeçalho WWW-Authenticate; 403 significa que a autenticação está correta, mas a ação não é permitida. 404 diz que o recurso não existe – ou que o servidor não quer revelar que ele existe. 409 indica um conflito com o estado atual, 412 uma pré-condição que falhou, como If-Match, e 422 uma requisição sintaticamente correta, mas cujo conteúdo não pode ser processado. A RFC 6585 acrescenta 428 (pré-condição obrigatória) e 429 (excesso de requisições), este último opcionalmente com Retry-After; 503 é indisponibilidade temporária, também com Retry-After quando o tempo de espera pode ser calculado.

Por que importa

Um cliente vê o código antes de analisar o corpo; bibliotecas, proxies e caches se bifurcam apenas com base nele. Um 503 ou 429 é repetido por muitos clientes, um 400 ou 422 não; um 304 poupa a transferência, um 201 fornece o endereço do recurso criado. Um agente que usa uma API a partir da documentação precisa dessa convenção para não ter de adivinhar a cada erro – e para não repetir, após um timeout, uma requisição que já surtiu efeito.

Como aplicar

• Associe cada classe de erro do domínio a exatamente um código e a um tipo de problema legível por máquina; a tabela pertence à documentação da API.
• Responda à criação com 201 e Location ou com o identificador no corpo; responda a exclusões e revogações bem-sucedidas com 204, sem corpo.
• Use 400 para entradas sintaticamente quebradas e 422 para as inválidas quanto ao conteúdo – ou apenas um dos dois, mas de forma consistente.
• Exija pré-condições com If-Match e entity tags e responda a falhas com 412; quem quiser impô-las responde com 428 às requisições sem pré-condição.
• Envie Retry-After em 429 e 503 sempre que o tempo de espera for conhecido; clientes e agentes o respeitam, em vez de repetir imediatamente.
• Em APIs, use redirecionamentos 307 ou 308, que preservam método e corpo; com 301 e 302, a RFC 9110 permite que o cliente converta POST em GET por razões históricas.

Armadilhas

Usar 404 para ocultar decisões de autorização é legítimo, mas precisa ser consistente; caso contrário, a divergência revela a existência do recurso. Códigos próprios fora das faixas registradas confundem os intermediários. Um 200 com {"error": ...} no corpo é colocado em cache, não é repetido e é contado como sucesso pelo monitoramento.

Sucesso parcial em requisições em lote

Uma requisição que processa vários elementos tem vários resultados. O código de status descreve a requisição como um todo: 200 (ou 207 Multi-Status, conforme a RFC 4918) quando ela foi aceita e processada, 4xx apenas quando foi inválida como um todo. Cada elemento traz seu próprio status e, se for o caso, seu objeto de problema no corpo da resposta, em um local documentado; o GraphQL procede da mesma forma com erros de campo ao lado de data. O monitoramento conta os erros de elementos separadamente dos erros de requisição, para que um 200 com noventa por cento dos elementos falhos não passe por sucesso. Para todo o resto vale a regra do artigo: um erro que afeta a requisição inteira pertence ao código de status, não a um 200.