Busca de Códigos HTTP Status

Códigos HTTP Status — Referência Completa de 100 a 511

Toda resposta HTTP de um servidor inclui um código de três dígitos que diz ao cliente o que aconteceu. Os códigos são agrupados em cinco categorias: 1xx (informativos), 2xx (sucesso), 3xx (redirecionamento), 4xx (erro cliente) e 5xx (erro servidor). Esta referência lista todos os 60+ códigos registrados com nomes, descrições, casos de uso comuns e links para os RFCs que os definem. Cada card também carrega selos de engenharia — Cacheável (conforme o conjunto cacheável heurístico do RFC 9111), Re-tentável (seguro para tentar de novo com backoff), Mantém método e Transfere SEO — para que engenheiros de plantão escrevendo camadas de retry, cache ou redirecionamento saibam num relance se um código é seguro para retentar ou cachear. Filtre por categoria ou por Cacheável/Re-tentável, busque por número ou palavra-chave pensando em fluxos com curl/Postman/observabilidade, e revise as orientações sobre Retry-After, X-RateLimit e RFC 7807 Problem Details nas perguntas frequentes.

O que são códigos de status HTTP e como são organizados?

Códigos de status HTTP são números de três dígitos retornados por um servidor em resposta à requisição de um cliente, definidos principalmente na RFC 9110 (HTTP Semantics, 2022) que substituiu a RFC 7231. São agrupados em cinco classes pelo primeiro dígito: 1xx informacional (requisição recebida, continuando), 2xx sucesso (requisição recebida, entendida e aceita com sucesso), 3xx redirecionamento (necessária ação adicional para completar a requisição), 4xx erro do cliente (a requisição contém sintaxe ruim ou não pode ser cumprida) e 5xx erro do servidor (o servidor falhou em cumprir uma requisição válida). O registro completo é mantido pela IANA, e atualmente inclui cerca de 70 códigos. Clientes devem tratar códigos desconhecidos como o x00 genérico da sua classe — então um código novo 499 deve ser tratado como 400 por um cliente que não o reconhece.

Qual a diferença entre 401 Unauthorized e 403 Forbidden?

Estes são confundidos rotineiramente. 401 Unauthorized significa "você não autenticou — forneça credenciais." A resposta deve incluir um cabeçalho WWW-Authenticate dizendo ao cliente qual esquema de auth usar (Basic, Bearer, Digest). A mesma requisição com credenciais válidas teria sucesso. 403 Forbidden significa "eu sei quem você é, e você não tem permissão." Re-autenticar não vai ajudar; as credenciais são reconhecidas mas falta permissão para este recurso. O nome 401 é historicamente enganoso — "unauthorized" deveria realmente ser "unauthenticated." Na prática, muitas APIs retornam 401 incorretamente para erros de permissão. RFC 9110 declara explicitamente que 403 deve ser usado quando o servidor entendeu a requisição mas se recusa a autorizá-la. Um código relacionado sutil é 407 Proxy Authentication Required, idêntico a 401 mas para um servidor proxy na cadeia.

Quando devo usar redirecionamentos 301 vs 302 vs 307 vs 308?

Os quatro redirecionam, mas diferem em duas dimensões: permanente vs temporário, e se o método da requisição pode mudar. 301 Moved Permanently e 308 Permanent Redirect ambos sinalizam que o recurso se moveu permanentemente — buscadores transferem autoridade de links. 302 Found e 307 Temporary Redirect sinalizam movimento temporário. A diferença de preservação de método é crítica: 301 e 302 historicamente permitem que clientes mudem POST para GET no redirecionamento (por ambiguidade de conformidade RFC), enquanto 307 e 308 estritamente exigem mesmo método e corpo. Para migrações SEO, use 301. Para endpoints POST que se movem, use 308 para preservar o corpo. Para balanceamento de carga ou testes A/B, use 302 ou 307. Bing e Google declararam explicitamente que 308 é tratado equivalentemente a 301 para fins de ranking.

O que significa 429 Too Many Requests e como tratar?

429 (RFC 6585) significa que o cliente enviou requisições demais em um dado tempo e está sendo limitado por taxa. A resposta deve incluir um cabeçalho Retry-After — um inteiro delta-segundos ("Retry-After: 60") ou um HTTP-date — dizendo ao cliente quando tentar novamente. Clientes bem comportados devem implementar backoff exponencial com jitter: não tente novamente exatamente no tempo Retry-After (todo cliente bateria de uma vez), tente entre Retry-After e Retry-After + jitter aleatório. Cabeçalhos adicionais comumente vistos mas não na RFC: X-RateLimit-Limit (o teto), X-RateLimit-Remaining (chamadas restantes na janela atual), X-RateLimit-Reset (timestamp Unix quando a janela reseta). O draft IETF draft-ietf-httpapi-ratelimit-headers propõe cabeçalhos padronizados RateLimit e RateLimit-Policy. Muitas APIs também retornam 503 com Retry-After para o mesmo propósito; o sinal chave é Retry-After.

O que é 418 I'm a teapot e é real?

418 I'm a teapot é o Easter egg mais famoso em HTTP. Origina-se da RFC 2324 (Hyper Text Coffee Pot Control Protocol), uma piada de 1º de abril publicada em 1º de abril de 1998. O significado pretendido era que um bule, quando solicitado a preparar café, deve responder com este status. Não faz parte da especificação real do HTTP (RFC 9110 não o inclui), e a IANA não o registra. Porém, muitos frameworks web e bibliotecas (Node.js, Go, Python, Rust) trazem constantes para HTTP 418 porque desenvolvedores genuinamente o usam para endpoints caprichosos ou ocultos. O robots.txt do Google por anos retornou 418 para certos user agents. Reserve 418 para piadas e honeypots — nunca use para semântica de erro real, porque clientes explicitamente não são obrigados a tratá-lo.

Qual a diferença entre 500, 502, 503 e 504?

Os quatro são erros do lado do servidor mas indicam modos de falha diferentes. 500 Internal Server Error é o pega-tudo genérico quando uma exceção inesperada ocorreu no código da aplicação — um NullPointerException, uma promise rejeitada não tratada, uma query de banco que explodiu. 502 Bad Gateway significa que um servidor upstream retornou uma resposta inválida para um gateway/proxy (como NGINX falando com um backend mal comportado). 503 Service Unavailable significa que o servidor está temporariamente sobrecarregado ou em manutenção e está intencionalmente rejeitando requisições; deve incluir Retry-After. 504 Gateway Timeout significa que um gateway/proxy esperou por um servidor upstream e expirou antes de obter resposta. A distinção importa para ops: 500 significa "corrigir o código," 502 significa "checar o serviço backend," 503 significa "escalar," e 504 significa "checar timeouts de rede/upstream." Cloudflare adiciona códigos não padrão 520-527 para falhas de borda mais granulares.

O que significa 422 Unprocessable Entity vs 400 Bad Request?

400 Bad Request significa que a sintaxe está errada: JSON malformado, cabeçalhos obrigatórios faltando, formato de query string inválido — o servidor nem consegue parsear o que você enviou. 422 Unprocessable Entity (originalmente do WebDAV RFC 4918, popularizado por APIs REST) significa que a sintaxe está correta mas a semântica está errada: o JSON parseia limpamente, mas "email" não é um endereço de e-mail válido, ou "idade" é -5, ou "endDate" é antes de "startDate". RFC 9110 reafirma 422 para a audiência HTTP mais ampla. A maioria das APIs REST modernas (Stripe, GitHub, Rails) usa 422 para erros de validação, o que permite a clientes distinguir "meu código gerou JSON inválido" de "meu código gerou JSON válido com valores inválidos." Combine 422 com um corpo JSON listando os erros no nível de campo (RFC 7807 Problem Details é o formato padrão). 409 Conflict é um código relacionado para conflitos de estado como criação de recurso duplicado.

Quais são os códigos de status menos conhecidos que devo saber?

Além dos comuns, vários códigos de nicho resolvem problemas reais. 100 Continue é usado com Expect: 100-continue para evitar enviar um corpo grande se o servidor for rejeitá-lo. 103 Early Hints (RFC 8297) permite que servidores enviem cabeçalhos Link antes da resposta final, habilitando pré-carregamento do navegador. 226 IM Used é para codificação delta (raro). 308 Permanent Redirect é o 301 que preserva método. 410 Gone sinaliza que um recurso foi deliberadamente removido e é improvável que retorne — mais forte que 404 e bom para des-indexação SEO. 451 Unavailable For Legal Reasons (RFC 7725, nomeado em homenagem a Fahrenheit 451) é usado para remoção de conteúdo ordenada por tribunal. 425 Too Early previne ataques de replay em TLS 1.3 0-RTT. 428 Precondition Required força clientes a usar If-Match para requisições condicionais. 511 Network Authentication Required é o que portais cativos deveriam retornar. Conhecê-los permite comunicar intenção com precisão.

Quais códigos HTTP são cacheáveis por padrão?

O RFC 9111 (HTTP Caching) define um conjunto específico de respostas heuristicamente cacheáveis por padrão — ou seja, um cache compartilhado pode armazená-las mesmo sem um header Cache-Control ou Expires explícito. Esse conjunto é: 200 OK, 203 Non-Authoritative Information, 204 No Content, 206 Partial Content, 300 Multiple Choices, 301 Moved Permanently, 308 Permanent Redirect, 404 Not Found, 405 Method Not Allowed, 410 Gone, 414 URI Too Long e 451 Unavailable For Legal Reasons. A ferramenta marca cada um com um selo Cacheável, e o filtro Só cacheáveis reduz a grade exatamente a esta lista. Três ressalvas: (1) isto é o padrão — qualquer resposta ainda pode ser tornada cacheável ou não com diretivas Cache-Control explícitas; (2) respostas com no-store, private ou um header Vary: * nunca são armazenadas; e (3) erros como 404 e 410 são cacheados apenas brevemente usando frescor heurístico (tipicamente uma fração do tempo desde Last-Modified). Na dúvida, defina Cache-Control explicitamente em vez de confiar no conjunto heurístico.

Quais códigos 4xx e 5xx são seguros para retentar automaticamente?

A segurança do retry depende de a requisição ser idempotente e de a falha ser transitória. Os códigos que vale a pena retentar automaticamente — sempre com backoff exponencial e jitter, e honrando qualquer header Retry-After — são: 408 Request Timeout, 425 Too Early, 429 Too Many Requests, 500 Internal Server Error (apenas para métodos idempotentes como GET/PUT/DELETE), 502 Bad Gateway, 503 Service Unavailable e 504 Gateway Timeout. A ferramenta os marca com um selo Re-tentável e o filtro Só re-tentáveis os isola. Nunca retente cegamente 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict ou 422 Unprocessable Content — a própria requisição está errada e retentá-la idêntica vai falhar de novo. Para um 500 num POST não idempotente, retentar arrisca criar duplicatas; use uma chave de idempotência (como Stripe e a maioria das APIs de pagamento) para que o retry seja seguro. Para 429 e 503, prefira o Retry-After fornecido pelo servidor ao seu próprio temporizador, e adicione jitter para que uma frota de clientes não retente em sincronia (efeito manada) no instante em que a janela reseta.

Recursos Principais

• Todo código HTTP status registrado IANA (60+) cobrindo 100 a 511
• Descrições detalhadas para os 25 códigos mais comuns (200, 301, 304, 401, 403, 404, 429, 500, 503, etc.)
• Busca por número de código ou palavra-chave em nomes e descrições
• Filtro por categoria: 1xx Informativo, 2xx Sucesso, 3xx Redirecionamento, 4xx Erro Cliente, 5xx Erro Servidor
• Indicadores de categoria codificados por cor para reconhecimento visual instantâneo
• Links diretos ao RFC definidor para cada código (RFC 9110, RFC 6585, etc.)
• Botões de salto rápido para os quatro códigos mais buscados (200, 301, 404, 500)
• Copia qualquer código de status para a área de transferência com um clique para relatórios de bug e documentação
• Exemplos de casos de uso explicando quando cada código é apropriado
• Cobre adições modernas: 103 Early Hints, 308 Permanent Redirect, 425 Too Early, 451 Legal
• Inclui 418 I'm a teapot do RFC 2324 para completude
• JavaScript puro — sem bibliotecas externas
• Funciona offline após o primeiro carregamento
• Layout de grade responsivo para celular e desktop
• 100% no cliente — nenhuma requisição é feita pela busca