Guia completo de códigos de status HTTP

Por que isso importa

Um backend devolve 200 OK com {"error": "Unauthorized"} no corpo. O handler genérico do front trata como sucesso porque o status foi 200. O login entra em loop. Erros triviais de status custam horas de engenharia — e distorcem crawlers SEO e relatórios de links quebrados. Saber qual código mandar faz parte do trabalho.

Três cenários reais

Designer de API

Escolher entre 400 / 401 / 403 / 404

Sem token? 401. Token sem permissão? 403. Recurso não existe? 404.

Comportamento previsível do cliente

Líder de SEO

Mover URL sem perder ranking

301 mantém PageRank; 302 é temporário e não transfere. Escolha de propósito.

Redirect permanente transfere ranking

DevOps

Sinalizar janela de manutenção

503 com cabeçalho Retry-After diz aos crawlers para voltar depois em vez de desindexar.

Motores de busca sabem tentar de novo

Cinco famílias num relance

Faixa	Família	Membros comuns
1xx	Informativo	100 Continue, 101 Switching Protocols
2xx	Sucesso	200 OK, 201 Created, 204 No Content
3xx	Redirecionamento	301, 302, 304 Not Modified, 308
4xx	Erro do cliente	400, 401, 403, 404, 422, 429
5xx	Erro do servidor	500, 502, 503, 504

Passo a passo — usando a referência

Abra a referência de status HTTP.

Busque por código ou descrição
Digite "401", "unauthorized" ou "rate limit". Códigos compatíveis sobem no topo.
Leia o significado canônico
Cada entrada explica o que a especificação diz, não só o que o curl imprime.
Veja uso no mundo real
Notas citam onde APIs populares (GitHub, Stripe, AWS) divergem um pouco.
Impacto SEO
Cada código é marcado com tratamento de busca (indexável ou não, transfere ranking ou não).
Copie uma linha
Cole descrição na doc da API ou comentário inline.

Distinção 401 vs 403

Cenário

POST /admin/users
(Sem cabeçalho Authorization)

Resposta recomendada

401 Unauthorized
WWW-Authenticate: Bearer realm="admin"

Mesmo endpoint, usuário com token sem escopo admin

Cenário

POST /admin/users
Authorization: Bearer eyJ...   (token válido, escopo viewer)

Resposta recomendada

403 Forbidden
{"error": "scope_admin_required"}

Grade da referência de status com categorias e selos SEO — Navegue por família, busque por código, copie descrições para suas APIs.

Dicas avançadas

422 para entrada bem formada mas semanticamente inválida (JSON com tipos errados). 400 é para pedido malformado.
204 No Content em deletes é mais explícito que 200 com corpo vazio — informa ausência intencional de payload.
Sempre inclua Retry-After com 429 / 503. Clientes inteligentes sabem quando voltar.
Evite 200 com error: ... no corpo. Anula propósito dos status HTTP e confunde monitoramento.

Armadilhas comuns

Erro comum

Devolver 404 para "você não pode acessar isso"

404 vago esconde existência — às vezes desejável (repos privados), mas em APIs autenticadas normais prefira 403 para cliente saber que é questão de permissão.

Erro comum

Cachear 302 para sempre

302 é temporário por especificação, mas alguns intermediários cacheiam agressivo. Se redirect é permanente, mande 301 (ou 308 para preservar método).

Erro comum

500 para erro do cliente

500 é erro de servidor. Cliente mandou dados ruins → 4xx — senão seu alerta dispara por bug no código deles.

Quando esta não é a ferramenta certa

Protocolo novo do zero — status HTTP ligam à semântica HTTP; gRPC, WebSockets e protocolos próprios têm convenções diferentes.
Erros em nível de app — códigos de aplicação vão no corpo junto ao HTTP.
Monitoramento — APM deve categorizar status automaticamente; esta referência é para decisões de design antes do deploy.

FAQ

Diferença entre 301 e 308?

Ambos redirects permanentes. 308 garante preservação do método HTTP; 301 historicamente permitiu POST → GET no follow.

O código 418 (I'm a teapot) é real?

Sim, RFC 2324 (1º de abril de 1998), reafirmada na RFC 7168. É piada, não usada em APIs de produção.

Devo expor códigos específicos de framework (419, 440)?

Evite códigos não padronizados se puder. Fique no conjunto registrado na IANA para clientes genéricos entenderem.

Próximos passos

Inspecione respostas com analisador de URL ao depurar comportamento estranho.
Consulte comandos Git/Linux durante triagem nas referências Git e Linux.
Verifique IP/ASN do servidor em erros 502/504 com consulta IP.

Por que isso importa

Três cenários reais

Designer de API

Escolher entre 400 / 401 / 403 / 404

Sem token? 401. Token sem permissão? 403. Recurso não existe? 404.

Comportamento previsível do cliente

Líder de SEO

Mover URL sem perder ranking

301 mantém PageRank; 302 é temporário e não transfere. Escolha de propósito.

Redirect permanente transfere ranking

DevOps

Sinalizar janela de manutenção

503 com cabeçalho Retry-After diz aos crawlers para voltar depois em vez de desindexar.

Motores de busca sabem tentar de novo

Cinco famílias num relance

Faixa	Família	Membros comuns
1xx	Informativo	100 Continue, 101 Switching Protocols
2xx	Sucesso	200 OK, 201 Created, 204 No Content
3xx	Redirecionamento	301, 302, 304 Not Modified, 308
4xx	Erro do cliente	400, 401, 403, 404, 422, 429
5xx	Erro do servidor	500, 502, 503, 504

Passo a passo — usando a referência

Abra a referência de status HTTP.

Busque por código ou descrição
Digite "401", "unauthorized" ou "rate limit". Códigos compatíveis sobem no topo.
Leia o significado canônico
Cada entrada explica o que a especificação diz, não só o que o curl imprime.
Veja uso no mundo real
Notas citam onde APIs populares (GitHub, Stripe, AWS) divergem um pouco.
Impacto SEO
Cada código é marcado com tratamento de busca (indexável ou não, transfere ranking ou não).
Copie uma linha
Cole descrição na doc da API ou comentário inline.

Distinção 401 vs 403

Cenário

POST /admin/users
(Sem cabeçalho Authorization)

Resposta recomendada

401 Unauthorized
WWW-Authenticate: Bearer realm="admin"

Mesmo endpoint, usuário com token sem escopo admin

Cenário

POST /admin/users
Authorization: Bearer eyJ...   (token válido, escopo viewer)

Resposta recomendada

403 Forbidden
{"error": "scope_admin_required"}

Dicas avançadas

422 para entrada bem formada mas semanticamente inválida (JSON com tipos errados). 400 é para pedido malformado.
204 No Content em deletes é mais explícito que 200 com corpo vazio — informa ausência intencional de payload.
Sempre inclua Retry-After com 429 / 503. Clientes inteligentes sabem quando voltar.
Evite 200 com error: ... no corpo. Anula propósito dos status HTTP e confunde monitoramento.

Armadilhas comuns

Erro comum

Devolver 404 para "você não pode acessar isso"

404 vago esconde existência — às vezes desejável (repos privados), mas em APIs autenticadas normais prefira 403 para cliente saber que é questão de permissão.

Erro comum

Cachear 302 para sempre

302 é temporário por especificação, mas alguns intermediários cacheiam agressivo. Se redirect é permanente, mande 301 (ou 308 para preservar método).

Erro comum

500 para erro do cliente

500 é erro de servidor. Cliente mandou dados ruins → 4xx — senão seu alerta dispara por bug no código deles.

Quando esta não é a ferramenta certa

Protocolo novo do zero — status HTTP ligam à semântica HTTP; gRPC, WebSockets e protocolos próprios têm convenções diferentes.
Erros em nível de app — códigos de aplicação vão no corpo junto ao HTTP.
Monitoramento — APM deve categorizar status automaticamente; esta referência é para decisões de design antes do deploy.

FAQ

Diferença entre 301 e 308?

Ambos redirects permanentes. 308 garante preservação do método HTTP; 301 historicamente permitiu POST → GET no follow.

O código 418 (I'm a teapot) é real?

Sim, RFC 2324 (1º de abril de 1998), reafirmada na RFC 7168. É piada, não usada em APIs de produção.

Devo expor códigos específicos de framework (419, 440)?

Evite códigos não padronizados se puder. Fique no conjunto registrado na IANA para clientes genéricos entenderem.

Próximos passos

Inspecione respostas com analisador de URL ao depurar comportamento estranho.
Consulte comandos Git/Linux durante triagem nas referências Git e Linux.
Verifique IP/ASN do servidor em erros 502/504 com consulta IP.