Códigos de status HTTP

Um padrão com três décadas de desvio

Os códigos de status HTTP passaram por várias gerações de especificação. A RFC 1945 (maio de 1996) padronizou o HTTP/1.0 com as categorias básicas 1xx-5xx. A RFC 2616 (junho de 1999) trouxe o HTTP/1.1 e foi a referência canônica por mais de uma década. A série 7230-7235 (junho de 2014) dividiu o HTTP/1.1 em várias especificações por tópico. O padrão consolidado atual é a RFC 9110 «HTTP Semantics» (junho de 2022), que torna obsoleta a divisão 7230-7235 e é a citação certa para o trabalho moderno. O registro completo e ativo dos códigos atribuídos fica no registro de códigos de status HTTP da IANA.

As cinco categorias num relance

• 1xx Informativo: resposta provisória. A requisição foi recebida e o servidor está continuando a processá-la. Raro na prática; útil para upgrades de protocolo e para o moderno 103 Early Hints (que permite aos servidores pré-carregar recursos críticos antes de a resposta completa estar pronta).
• 2xx Sucesso: a requisição foi recebida, compreendida e aceita. 200 OK é o caso do dia a dia; 201 Created para a criação de recursos; 204 No Content para ações bem-sucedidas que não têm nada a retornar.
• 3xx Redirecionamento: ação adicional necessária. Os redirecionamentos clássicos (301 Moved Permanently, 302 Found, 307 Temporary Redirect, 308 Permanent Redirect) mais o 304 Not Modified para validação de cache.
• 4xx Erro do cliente: o cliente fez algo errado: sintaxe ruim, autenticação ausente, requisitar algo que não existe. A maior categoria no tráfego do mundo real.
• 5xx Erro do servidor: o servidor se atrapalhou. A requisição era válida; o servidor simplesmente não conseguiu entregar. Estes são os que acordam os engenheiros de plantão.

As comparações «vs.» que confundem todo mundo

401 vs. 403. O par mais confundido de todos. 401 Unauthorized significa «você não se autenticou, tente fazer login» (o nome é tecnicamente enganoso: é sobre autenticação, não autorização). 403 Forbidden significa «você está autenticado, mas não tem permissão para fazer isto»: suas credenciais são válidas, mas não concedem acesso a este recurso. Um uso incorreto comum: retornar 403 para requisições não autenticadas quando o correto é 401 com um cabeçalho WWW-Authenticate.

301 vs. 302 vs. 307 vs. 308. Dois eixos, permanente vs. temporário, e o comportamento de preservação de método:

Se você está redirecionando requisições GET para fins de SEO, o 301 é a escolha convencional. Se você está redirecionando requisições POST ou PUT e quer o método preservado, precisa do 307 ou do 308.

400 vs. 422. O 400 Bad Request é para requisições sintaticamente malformadas: JSON inválido, cabeçalhos obrigatórios ausentes, parâmetros de consulta malformados. O 422 Unprocessable Entity (originalmente um código do WebDAV, amplamente adotado por APIs REST) é para requisições sintaticamente válidas com problemas semânticos: o JSON é analisado corretamente, mas os valores falham na validação de negócio (quantidade negativa em um pedido, e-mail já em uso). Muitas APIs usam os dois.

502 vs. 503 vs. 504. Três modos diferentes de falha de upstream:

• 502 Bad Gateway: o proxy / gateway recebeu uma resposta inválida do servidor upstream.
• 503 Service Unavailable: o servidor está sobrecarregado ou em manutenção. Muitas vezes acompanhado de um cabeçalho Retry-After.
• 504 Gateway Timeout: o servidor upstream não respondeu a tempo.

404 vs. 410. O 404 Not Found é «não sabemos se isto existe ou não.» O 410 Gone é «isto já existiu, foi removido permanentemente.» Impacto no SEO: o Google trata o 410 como um sinal mais forte de que o conteúdo está permanentemente indisponível e o remove do índice mais rápido do que faz com o 404.

Convenções de API REST

As APIs REST modernas convergiram para um conjunto bastante consistente de convenções sobre o que os códigos de status significam para cada ação:

Implicações de SEO

• 200 OK: o Google indexa a página normalmente.
• 301 Moved Permanently: o Google atualiza a URL indexada para a nova e transfere os sinais de ranking.
• 302 Found / 307 Temporary Redirect: o Google mantém a URL original indexada; o ranking permanece com a original.
• 308 Permanent Redirect: o Google o trata como o 301: o ranking é transferido.
• 304 Not Modified: usado pelo Googlebot para requisições condicionais; sinaliza que o conteúdo em cache pode ser reutilizado.
• 404 Not Found: o Google remove a URL do seu índice após alguns rastreamentos.
• 410 Gone: o Google remove a URL mais rápido do que para o 404; o sinal mais forte de «removido permanentemente».
• 503 Service Unavailable com Retry-After: diz ao Googlebot para voltar mais tarde. Use durante janelas de manutenção; evite usar o 503 para erros genuínos (o Google interpreta 503s sustentados como instruções para não rastrear).
• 5xx sustentado: o Google reduz a taxa de rastreamento e pode acabar removendo a URL do índice por completo.

Códigos famosos e culturais

• 418 I'm a teapot: uma piada do Dia da Mentira da RFC 2324 (Hyper Text Coffee Pot Control Protocol, 1 de abril de 1998). Quando a IETF propôs removê-lo da especificação em 2017, a campanha «Save 418» conseguiu mantê-lo nos registros. Algumas APIs o usam como um marcador de «isto não é real»; fora isso, é inofensivo.
• 451 Unavailable For Legal Reasons: RFC 7725 (2015), batizado em homenagem ao Fahrenheit 451 de Ray Bradbury. Retornado quando o conteúdo é censurado por ordem judicial ou solicitação governamental.
• A série 520-527 da Cloudflare: não padronizada, usada pela Cloudflare para indicar falhas específicas de conexão com o servidor upstream. Comum quando um site atrás da Cloudflare tem problemas.
• O 444 No Response do Nginx: específico do Nginx, retornado quando o servidor fecha a conexão sem enviar nenhuma resposta.
• O histórico 420 Enhance Your Calm do Twitter: um código de limite de taxa já removido, usado pela API anterior do Twitter; substituído pelo padrão 429.

Erros comuns

1. Usar 200 OK para erros com um corpo de erro. Retornar {"error": "not found"} com um status 200 confunde toda camada de cache, ferramenta de monitoramento e SDK de cliente. Use o código de status certo.
2. Retornar 403 para requisições não autenticadas. O código certo é 401 com um cabeçalho WWW-Authenticate.
3. Usar 302 quando você quer dizer 301. Se a mudança é permanente, os motores de busca precisam do 301 para transferir o ranking. O 302 mantém a URL antiga indexada.
4. Usar 301 ou 302 para redirecionamentos de POST/PUT. Historicamente, esses permitiam aos clientes mudar o método para GET. O 307 e o 308 preservam estritamente o método original.
5. Retornar 500 quando se quer dizer 503. Se o servidor está sobrecarregado ou em manutenção, 503 com Retry-After é o sinal correto, tanto para os clientes quanto para o Googlebot.
6. Usar 404 para páginas removidas permanentemente. O 410 Gone é o sinal mais forte e é removido dos índices dos motores de busca mais rápido.
7. Esquecer o cabeçalho Location em respostas 201 e 3xx. O cabeçalho Location é o que diz ao cliente onde o novo recurso fica ou para onde redirecionar. Sem ele, os clientes não conseguem navegar.

Mais perguntas frequentes

Quando devo retornar 422 em vez de 400?

O 400 Bad Request significa que a própria requisição está malformada: JSON inválido, cabeçalhos obrigatórios ausentes, parâmetros de consulta malformados. O 422 Unprocessable Entity significa que a requisição está bem-formada, mas contém erros semânticos que impedem o processamento: um campo de quantidade definido como um número negativo, um endereço de e-mail que já está em uso, uma data no passado para um campo que só aceita o futuro. As convenções modernas de API REST convergiram para essa divisão, com a maioria das grandes APIs (GitHub, Stripe, Twilio) usando o 422 para erros de validação.

Por que a Cloudflare às vezes retorna 520, 521, 522…?

Os códigos 520-527 são específicos da Cloudflare, sinalizando diferentes formas pelas quais a borda deles não conseguiu alcançar seu servidor de origem. O 520 é o genérico «o servidor web retornou um erro desconhecido»; o 521 significa que a sua origem recusou a conexão; o 522 é um tempo limite de conexão com a sua origem; o 524 significa que a sua origem demorou demais para responder. Eles não estão no registro da IANA, mas são amplamente encontrados quando sites atrás da Cloudflare têm problemas de backend.

Meu navegador vai me mostrar qual código a minha API retornou?

Sim, abra o DevTools → aba Network, clique na requisição e olhe a coluna «Status». Os navegadores também exibem páginas genéricas para alguns códigos (o jogo do dinossauro nas falhas de conexão do Chrome, as páginas 404 / 500 padrão); mas o código numérico real está sempre na resposta.

O que é o 103 Early Hints?

Um código 1xx relativamente novo (RFC 8297, 2017) que permite ao servidor enviar cabeçalhos Link: rel=preload antes de a resposta completa estar pronta, dizendo ao navegador para começar a buscar recursos críticos (CSS, fontes, imagens) cedo. Agora é suportado pelo Chrome e entregue pela Cloudflare, Fastly e outras CDNs como uma otimização de desempenho.

Posso inventar meu próprio código de status?

Tecnicamente sim (o HTTP permite qualquer código de 3 dígitos na faixa 100-599). Na prática, não: clientes, proxies e caches tratam códigos desconhecidos pelo primeiro dígito (então 4xx = erro do cliente, de forma genérica, 5xx = erro do servidor). Alguns fornecedores fazem isso (os 520 da Cloudflare, o 444 do Nginx), mas, a menos que você controle as duas pontas da conexão, limite-se ao registro da IANA. Inventar um 299 não vai quebrar nada, mas também não vai comunicar coisa alguma.

Por que o «código de status» se chama «status» e não «código de erro»?

Porque a maioria deles não são erros. O 200 OK é o código de status mais retornado do mundo: significa «tudo correu bem.» Os códigos comunicam o status da requisição: sucesso, redirecionamento, erro do cliente, erro do servidor. Chamá-los de «códigos de erro» tende para os casos negativos que são registrados e notados; os códigos de sucesso fazem seu trabalho silenciosamente a cada microssegundo.