Status HTTP explicados pela cara que cada um faz

Todo mundo decora o 200 e o 404. Depois disso a conversa fica nebulosa, e aí alguém devolve 200 OK com {"erro": "deu ruim"} no corpo e o cliente da API passa a vida achando que está tudo bem.

Então vamos combinar: cada código é uma frase curta que o servidor está falando. Se você souber a frase, nunca mais escolhe errado.

A regra do primeiro dígito#

O primeiro número já conta a história quase toda:

Família	Tradução livre	De quem é a culpa
1xx	"calma, ainda estou processando"	de ninguém
2xx	"deu certo"	de ninguém
3xx	"procura em outro lugar"	de ninguém
4xx	"você errou"	sua
5xx	"eu errei"	minha

Essa divisão entre 4xx e 5xx é a parte que importa mais. Ela decide quem vai ser acordado às três da manhã.

200 OK#

Funcionou. Não tem muito o que falar.

O problema do 200 é o abuso: ele virou o padrão de quem não quis pensar. Se a requisição falhou, devolver 200 com uma mensagem de erro no JSON não está "simplificando o cliente": está obrigando todo mundo a abrir o corpo da resposta para descobrir o que aconteceu. E algum cliente vai esquecer.

301 Moved Permanently#

Mudei de endereço e não volto mais. Navegadores e buscadores levam isso a sério: eles guardam a informação e param de visitar o endereço antigo.

É aí que mora o perigo. Um 301 feito por engano fica em cache no navegador de quem visitou, e você não tem como pedir de volta. Quando estiver testando redirecionamento, use 302, ou melhor, 307, que preserva o método da requisição. Quando tiver certeza absoluta, troque para 301.

404 Not Found#

O famoso. Não encontrei nada nesse endereço.

Tem um detalhe elegante aqui que pouca gente usa de propósito: 404 é a resposta certa quando o recurso existe mas a pessoa não deveria nem saber disso. Devolver 403 Forbidden confirma que o recurso está lá, e isso já é informação demais. GitHub faz exatamente isso com repositórios privados.

418 I'm a teapot#

Esse veio da RFC 2324, um protocolo de brincadeira para cafeteiras publicado em primeiro de abril de 1998. A ideia: se você pedir café para um bule de chá, ele responde 418.

Já tentaram remover o código das implementações mais de uma vez. A internet reagiu tão mal que ele continua lá até hoje. Não use em produção, mas saiba que existe, porque uma hora você vai ver um numa resposta e vai rir sozinho.

500 Internal Server Error#

Algo explodiu do meu lado. É o status mais honesto da lista e o mais inútil para quem recebe: ele não diz nada além de "falhou aqui dentro".

Isso é intencional. Vazar o stack trace numa resposta é entregar a estrutura interna do seu sistema para qualquer um. O lugar da mensagem detalhada é o seu log, com um identificador de correlação que você devolve para a pessoa:

{
  "error": "internal_error",
  "requestId": "7f3c9a21"
}

Aí quem está integrando te manda o requestId, você busca no log e descobre em dez segundos o que levaria uma hora de ida e volta.

O resumo que eu colaria na parede#

• Deu certo e criou algo? 201, com Location.
• Deu certo e não tem o que devolver? 204.
• O cliente mandou porcaria? 400.
• Não sei quem é você? 401. Sei quem é e você não pode? 403.
• Não quero nem confirmar que isso existe? 404.
• Explodiu aqui? 500. Explodiu aqui mas já volta? 503 com Retry-After.

Nenhuma dessas escolhas é sobre purismo. É sobre a pessoa do outro lado conseguir descobrir o que fazer sem precisar te chamar no WhatsApp.