Referência de Códigos de Status HTTP

A Referência de Códigos de Status HTTP é um índice completo e pesquisável de cada código de status definido nas especificações HTTP — desde 100 Continue até 511 Network Authentication Required. Cada entrada mostra o nome canônico, a RFC que o define, o que o código realmente significa, quando enviá-lo, quando não enviá-lo e as armadilhas comuns que afetam bases de código reais. Um filtro em tempo real e botões de categoria permitem que você salte de classe em classe com um único clique.

Ao contrário de uma folha de dicas (cheatsheet) estática, esta ferramenta oferece a cada código sua própria micro-página com três painéis codificados por cores (o que fazer / o que não fazer / armadilhas) e manipuladores prontos para colar para Express.js, Django, FastAPI e Go net/http. O diagrama animado mostra a requisição viajando do cliente para o servidor e o status escolhido retornando — útil para iniciantes que estão aprendendo o que um código de status realmente representa no fluxo da rede.

Por que uma referência de códigos de status é importante

Como usar a Referência de Códigos de Status HTTP

1. Consulta rápida. Digite um código (404) ou um fragmento de nome (teapot, gateway) na caixa de pesquisa no topo e envie. A entrada correspondente será aberta com o painel de detalhes completo.
2. Navegar por classe. Clique em qualquer um dos 5 botões (1xx, 2xx, 3xx, 4xx, 5xx) para filtrar a grade por essa classe. Clique em Tudo para redefinir.
3. Filtro em tempo real. A caixa de filtro logo acima da grade reduz os cartões conforme você digita — útil quando você lembra de metade de um nome como too many ou precondition.
4. Inspecionar um código. Clique em qualquer cartão para abrir seu painel de detalhes. Você verá o significado, quando usar, quando não usar, armadilhas comuns e um bloco de snippets para 4 frameworks.
5. Copiar um snippet. Use the seletor de abas e o pequeno botão Copiar para obter um manipulador pronto para colar.
6. Comparar vizinhos. O painel de detalhes termina com cartões irmãos da mesma classe (1xx / 2xx / 3xx / 4xx / 5xx) para uma comparação rápida lado a lado.

As cinco classes de status HTTP em resumo

Pares frequentemente confundidos

• 401 vs 403. 401 significa não autenticado — a requisição carece de credenciais válidas. 403 significa autenticado, mas não permitido — os dados de acesso estão corretos, mas o usuário não tem permissão.
• 404 vs 410. 404 significa desconhecido: talvez exista em algum lugar, talvez seja um erro de digitação. 410 significa removido deliberadamente: os mecanismos de busca devem removê-lo do índice.
• 301 vs 302 vs 307 vs 308. 301 / 308 are permanentes (308 preserva estritamente o método e o corpo), 302 / 307 são temporários (307 preserva estritamente o método e o corpo). Use 307 / 308 para redirecionamentos de POST / PUT / PATCH.
• 400 vs 422. 400 significa que o corpo da requisição está malformado (JSON inválido, campo ausente). 422 significa que o corpo foi analisado corretamente, mas os valores falham nas regras de negócio (formato de e-mail inválido, quantidade fora do intervalo).
• 502 vs 503 vs 504. 502 significa que o upstream enviou dados inválidos. 503 significa que o servidor está sobrecarregado ou em manutenção. 504 significa que o upstream não respondeu a tempo.
• 409 vs 412. 409 é um conflito com o estado atual do recurso. 412 significa especificamente que um cabeçalho de pré-condição (If-Match, If-Unmodified-Since) foi avaliado como falso.

Cabeçalhos que se associam a códigos de status específicos

• 201 Created — deve incluir o Location apontando para o novo recurso.
• 301 / 302 / 307 / 308 — devem incluir o Location com a URL de destino.
• 304 Not Modified — deve ecoar os cabeçalhos que teriam aparecido em um 200 (ETag, Cache-Control, Vary).
• 401 Unauthorized — deve incluir o WWW-Authenticate listando os esquemas aceitos (Basic, Bearer).
• 405 Method Not Allowed — deve incluir o Allow listando os métodos que são permitidos.
• 413 / 429 / 503 — frequentemente incluem o Retry-After (segundos ou HTTP-date) para que os clientes recuem corretamente.
• 416 Range Not Satisfiable — deve incluir o Content-Range: bytes */<length>.

Códigos de status que você quase sempre pode ignorar

Alguns códigos são tecnicamente válidos, mais extremamente raros em APIs modernas: 305 Use Proxy (descontinuado), 306 (reservado, não utilizado), 305, 506 Variant Also Negotiates, 510 Not Extended e 508 Loop Detected. A maioria é mantida no registro por razões históricas. Se a sua biblioteca ou middleware emitir um deles, trate isso como um relatório de bug contra a biblioteca — não como uma dica para tratá-lo de forma especial.

FAQ

A ferramenta inclui códigos de outras RFCs além da 9110?

Sim. Ela abrange a RFC 9110 (semântica HTTP), RFC 6585 (4xx / 5xx adicionais), RFC 4918 (WebDAV), RFC 5842 (vínculos WebDAV), RFC 7725 (451), RFC 8297 (103 Early Hints), RFC 8470 (425 Too Early) e a famosamente divertida RFC 2324 (418 Teapot).

Esses códigos são válidos no HTTP/2 e HTTP/3?

Sim. As semânticas dos códigos de status são definidas na RFC 9110, que é o documento de semântica HTTP independente de versão. O HTTP/2 (RFC 9113) e o HTTP/3 (RFC 9114) apenas alteram a estrutura de quadros (framing) e o transporte.

Posso criar um link direto para um código específico?

Envie o formulário com um único código (por exemplo, 404) e o painel de detalhes será carregado abaixo do formulário. A URL mostrará a sua pesquisa e é segura para compartilhar — ao abri-la, o mesmo resultado será carregado.

Por que meu framework não me deixa retornar 418?

Versões mais antigas de algumas bibliotecas HTTP se recusam a emitir códigos que não estão em seu registro interno. A solução é atualizar a biblioteca ou, quando possível, escrever a linha de status manualmente.

Uma API deve algum dia retornar 200 com um corpo de erro?

Não. Monitoramento, tentativas de reenvio (retries) e intermediários assumem que 2xx significa sucesso. Se você precisar retornar uma estrutura de erro, retorne um 4xx ou 5xx apropriado e insira os detalhes estruturados dentro do corpo. O formato Problem Details para APIs HTTP (RFC 9457) é um bom modelo.

Existe um registro oficial de códigos de status HTTP?

Sim. A IANA mantém o registro em iana.org/assignments/http-status-codes. Esta ferramenta permanece sincronizada com esse registro e com as RFCs mais comumente citadas.