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. Filtre por categoria, busque por número ou palavra-chave, ou copie qualquer código para a área de transferência para documentação, relatórios de bug ou mensagens de commit.

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

Os dois códigos parecem similares mas significam coisas diferentes:

- **401 Unauthorized** — o cliente não se autenticou, ou a autenticação falhou. O conserto é fazer login ou enviar um token válido. A resposta deve incluir um header WWW-Authenticate dizendo ao cliente como. Confusamente, apesar do nome, 401 significa 'não autenticado'.

- **403 Forbidden** — o cliente está autenticado mas não tem permissão para este recurso específico. Tentar de novo com as mesmas credenciais não resolverá; o usuário simplesmente não tem acesso.

Um padrão comum em aplicações sensíveis à segurança é retornar 404 Not Found em vez de 403 para evitar revelar que um recurso restrito existe. Por exemplo, GitHub retorna 404 para repos privados aos quais você não tem acesso, não 403.

Devo usar 301 ou 308 para um redirect permanente?

Depende do método HTTP. Os dois códigos significam a mesma coisa semanticamente (ambos são redirects permanentes), mas se comportam diferente quando a requisição original era POST/PUT/DELETE:

- **301 Moved Permanently** — RFC 9110 permite explicitamente que clientes mudem o método para GET ao seguir um 301. Historicamente, a maioria dos navegadores sempre fazia isso, mesmo para POST. Use 301 apenas para redirects GET.

- **308 Permanent Redirect** — preserva explicitamente o método original. POST continua POST, DELETE continua DELETE. Use 308 quando o redirect precisa funcionar para endpoints API.

Para sites que principalmente redirecionam requisições GET (p. ex., HTTP → HTTPS, www → não-www), 301 é bom e ligeiramente melhor suportado em clientes antigos. Para APIs e formulários, prefira 308.

A mesma distinção existe para redirects temporários: 302 (frouxo) vs 307 (preserva método).

Quando 422 Unprocessable Content é apropriado?

422 é o código certo quando a sintaxe da requisição é válida (JSON bem formado, content-type correto) mas o conteúdo *semântico* está errado. O exemplo clássico é um formulário de cadastro onde:

- O JSON parseia corretamente → não é 400
- O campo email está presente → não é erro de campo faltando
- Mas o endereço de email está malformado (p. ex., 'not-an-email') → 422 Unprocessable Content

Vs. 400 Bad Request que deve ser reservado para:

- JSON malformado (erro de parse)
- Campos obrigatórios faltando
- Header content-type errado

Na prática, muitas APIs usam 400 para tudo do lado cliente, e isso também é aceitável. A distinção importa quando você quer dar aos clientes uma maneira programática de distinguir 'conserte seus dados' de 'conserte o formato da sua requisição'. GitHub, Stripe e a maioria das APIs REST modernas usam 422 para erros de validação.

Qual o código certo para rate limiting?

**429 Too Many Requests** é a resposta canônica (RFC 6585). A resposta deve incluir:

- Um header **Retry-After** — em segundos (`Retry-After: 60`) ou uma data HTTP — dizendo ao cliente quando tentar de novo.
- Um corpo opcional explicando o limite. JSON como `{"error": "rate_limit_exceeded", "retry_after": 60}` é comum.
- Um trio opcional de headers **X-RateLimit-Limit**, **X-RateLimit-Remaining**, **X-RateLimit-Reset** para clientes rastrearem cotas.

Para proteção tipo DDoS onde você quer descartar a requisição silenciosamente, retornar 503 Service Unavailable com um Retry-After longo às vezes é usado como alternativa.

Evite usar 503 para rate-limiting normal porque diz ao cliente que o *servidor* está falhando, não o cliente. 429 é o sinal certo de 'você está enviando demais, diminua o ritmo'.

418 'I'm a teapot' é real?

Sim, mais ou menos. RFC 2324 define o HyperText Coffee Pot Control Protocol (HTCPCP), um RFC do Dia da Mentira de 1998 que especificou protocolos para fazer café sobre HTTP. Qualquer tentativa de fazer café com um bule de chá retorna 418 I'm a teapot.

O código é oficialmente registrado com a IANA mas é reservado como brincadeira. Em 2017 houve um esforço semi-sério para removê-lo das bibliotecas de servidor (Node.js brevemente removeu o suporte); a comunidade contra-atacou e a maioria dos stacks o manteve.

Casos de uso reais para 418 são limitados:

- **Brincadeiras do Dia da Mentira** — alguns sites retornam 418 de um endpoint /teapot.
- **Easter eggs** em documentação API.
- **Detecção de scrapers automatizados** — alguns sites retornam 418 para padrões de tráfego suspeitos.

Não use 418 em produção para erros reais — clientes não saberão o que fazer com ele.

O que significa 503 e como difere de 500?

**500 Internal Server Error** é um catch-all genérico: o servidor encontrou uma condição inesperada (um bug, uma exceção não tratada) e não pôde completar a requisição. A implicação é que tentar de novo imediatamente provavelmente não ajudará — algo está errado do lado servidor.

**503 Service Unavailable** é mais específico: o serviço está temporariamente fora, geralmente por sobrecarga, manutenção planejada ou lag de autoscaling. A implicação é que tentar mais tarde (frequentemente com o header **Retry-After** indicando quando) terá sucesso.

Algumas sutilezas:

- Um load balancer retornando 503 significa que o upstream está inalcançável. Olhe os logs do LB.
- Uma aplicação retornando 503 significa que está rejeitando requisições intencionalmente (modo manutenção, circuit breaker disparado).
- 503 nunca deve ser retornado por um crash de app — isso é território do 500.
- Cloudflare e outras CDNs têm seus próprios códigos 5xx (520, 521, 522, 523, 524, 525, 526, 527) para erros upstream específicos.

Por que a faixa 1xx é raramente vista em ferramentas?

Códigos 1xx são intermediários — são enviados *antes* da resposta final. A maioria das ferramentas (navegadores, curl, Postman) não os expõe porque quando a resposta final 2xx/3xx/4xx/5xx chega, o contexto 1xx já se foi.

Os três que você verá ocasionalmente:

- **100 Continue** — enviado quando um cliente usa `Expect: 100-continue` para perguntar se o servidor aceitará um upload grande antes de enviar o corpo.
- **101 Switching Protocols** — enviado durante um upgrade de protocolo, mais comumente o handshake WebSocket.
- **103 Early Hints** — mais novo (2017, RFC 8297). Permite ao servidor enviar dicas `Link: preload` antes da resposta final, para que o navegador comece a baixar CSS, JS e fontes em paralelo. Usado por Cloudflare e Fastly.

102 Processing existe (RFC 2518 para WebDAV) mas é mal usado fora de servidores WebDAV de nicho.

De onde vêm esses códigos?

Códigos HTTP status são definidos em múltiplos RFCs:

- **RFC 9110** (junho 2024) — a especificação atual de semântica HTTP, definindo os códigos base 1xx, 2xx, 3xx, 4xx, 5xx. Substituiu o RFC 7231 em 2024.
- **RFC 4918** — WebDAV (207 Multi-Status, 422 Unprocessable Content [agora em 9110], 423 Locked, 424 Failed Dependency, 507 Insufficient Storage).
- **RFC 6585** — Códigos HTTP adicionais (428, 429, 431, 511).
- **RFC 7538** — 308 Permanent Redirect.
- **RFC 7725** — 451 Unavailable For Legal Reasons.
- **RFC 8297** — 103 Early Hints.
- **RFC 8470** — 425 Too Early (TLS 1.3).
- **RFC 2324** — 418 I'm a teapot (brincadeira do Dia da Mentira).
- **IANA HTTP Status Code Registry** — a lista autoritativa de todos os códigos registrados.

Cada card nesta referência liga ao RFC que define aquele código de status, então você sempre pode ir à fonte autoritativa para casos limite.

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