Códigos de status HTTP: as decisões que cada número carrega

Cinco classes e a história por trás delas

O primeiro dígito do código entrega a categoria, e essa leitura já diz de que lado procurar o problema. É a triagem que um bom dev faz em meio segundo antes de abrir qualquer log. A semântica de cada classe está fixada na RFC 9110 (HTTP Semantics), o documento que hoje serve de referência para HTTP/1.1, HTTP/2 e HTTP/3 ao mesmo tempo.

Essa divisão parece óbvia hoje, mas levou décadas para se estabilizar. A numeração nasceu enxuta e foi ganhando códigos à medida que a web descobria novos problemas, de portais de Wi-Fi a rate limiting. Vale conhecer a linha do tempo porque ela explica por que existem pares quase idênticos como 302 e 307: eles são de eras diferentes, criados para corrigir ambiguidades da geração anterior.

1. Maio de 1996RFC 1945, HTTP/1.0

   A primeira versão documentada. Introduz a linha de status e um punhado de códigos (200, 301, 302, 400, 404, 500).

2. Janeiro de 1997RFC 2068, HTTP/1.1

   O primeiro recorte padronizado do HTTP/1.1, com conexões persistentes e mais códigos.

3. Junho de 1999RFC 2616, HTTP/1.1 revisada

   A revisão que foi a referência por quinze anos, num único documento monolítico.

4. Junho de 2014RFC 7230–7235

   A 2616 é quebrada em seis documentos (sintaxe, semântica, condicionais, range, cache, autenticação).

5. Junho de 2022RFC 9110 / 9111 / 9112

   A referência atual: semântica (9110), cache (9111) e HTTP/1.1 (9112). Obsoleta a série 723x e vale para todas as versões.

Redirecionar sem quebrar o método: 301 vs 308, 302 vs 307

O bloco 2xx é o mais tranquilo: 200 OK é o sucesso com corpo, 201 Created confirma que um POST criou um recurso (e costuma vir com o header Location) e 204 No Content é o sucesso mudo, típico de um DELETE. A armadilha de verdade está no 3xx, onde uma decisão sutil separa um redirect inofensivo de um bug que só aparece em produção: o código muda o método HTTP?

Aqui está o detalhe que a RFC 9110 registra em nota: por razões históricas, ao seguir um 301 (§15.4.2) ou um 302 (§15.4.3) o cliente PODE trocar o método de POST para GET. Os navegadores fazem isso há décadas, e a spec apenas descreve o comportamento real. Já o 307 Temporary Redirect (§15.4.8) e o 308 Permanent Redirect (§15.4.9) foram criados justamente para NÃO permitir essa troca: eles preservam o método e o corpo. O eixo permanente/temporário é ortogonal a isso, 301 e 308 são permanentes; 302 e 307 são temporários.

Exemplo trabalhado nº 1: um checkout envia um POST com o valor da compra. Se o servidor responde 302, o navegador segue o redirect trocando o método por GET e DESCARTANDO o corpo, o pagamento se perde no caminho e o endpoint de confirmação recebe um GET vazio. Com 307, o cliente repete o POST com o mesmo corpo. Veja a diferença byte a byte:

# Envio um formulário de pagamento com POST
POST /checkout HTTP/1.1
Host: loja.com
Content-Type: application/x-www-form-urlencoded

valor=199.90&metodo=cartao

# (A) Servidor responde 302 -> o navegador troca POST por GET
HTTP/1.1 302 Found
Location: /obrigado

GET /obrigado HTTP/1.1          <- metodo virou GET, corpo descartado
Host: loja.com

# (B) Mesmo fluxo com 307 -> o cliente REPETE metodo e corpo
HTTP/1.1 307 Temporary Redirect
Location: /obrigado

POST /obrigado HTTP/1.1         <- continua POST, corpo preservado
Host: loja.com
Content-Type: application/x-www-form-urlencoded

valor=199.90&metodo=cartao

A regra prática cai sozinha: para mover em definitivo uma página comum (GET) e preservar o ranking, 301 é o clássico e o Google trata 301 e 308 como equivalentes na consolidação de sinais. Para mover em definitivo um endpoint que recebe POST, use 308. Para um desvio passageiro, 302 basta, a menos que o método importe, e aí é 307. Consulte o significado, a RFC e a cacheabilidade de qualquer código na ferramenta abaixo antes de escolher.

4xx: o pedido é seu, 401 vs 403, 404 vs 410

O 4xx aponta para o que você mandou. Alguns são diretos: 400 Bad Request é pedido malformado, 405 Method Not Allowed é o verbo errado (e o servidor deve listar os aceitos no header Allow), 409 Conflict é choque de estado. Mas dois pares fazem gente perder horas procurando bug no lugar errado: 401 contra 403 e 404 contra 410. A diferença entre eles não é de gravidade, é de significado.

O outro par vive na fronteira entre backend e SEO. 404 Not Found (§15.5.5) diz “não existe nessa URL”, pode ser rota errada, recurso removido ou até o servidor escondendo que o recurso existe. 410 Gone (§15.5.11) é mais assertivo: “existiu e foi removido de propósito”. A pergunta que importa não é técnica, é o que cada um sinaliza ao Googlebot.

304 Not Modified: a conversa que economiza banda

O 304 Not Modified (§15.4.5) é o único 3xx que não redireciona nada, ele é o motor da revalidação de cache. A ideia: em vez de baixar de novo um recurso que talvez não tenha mudado, o cliente pergunta “mudou?” e, se a resposta for não, reaproveita o que já tem. Essa negociação usa validadores. O servidor manda um ETag (uma impressão digital do conteúdo, RFC 9110 §8.8.3) ou um Last-Modified (§8.8.2). Na próxima visita, o cliente devolve esses valores nos headers condicionais If-None-Match e If-Modified-Since (requisições condicionais, RFC 9110 §13; regras de cache, RFC 9111).

# Primeira visita: o servidor devolve o recurso + um validador
GET /static/app.css HTTP/1.1
Host: exemplo.com

HTTP/1.1 200 OK
Content-Type: text/css
Content-Length: 46080
Cache-Control: max-age=0, must-revalidate
ETag: "9f8a1c-b3d0"
Last-Modified: Tue, 07 Jul 2026 10:00:00 GMT

...46080 bytes de CSS...

# Recarga: o cliente pergunta "mudou?" com o validador que guardou
GET /static/app.css HTTP/1.1
Host: exemplo.com
If-None-Match: "9f8a1c-b3d0"
If-Modified-Since: Tue, 07 Jul 2026 10:00:00 GMT

# Nada mudou -> resposta sem corpo
HTTP/1.1 304 Not Modified
ETag: "9f8a1c-b3d0"
Cache-Control: max-age=0, must-revalidate
Date: Wed, 08 Jul 2026 09:00:00 GMT

(sem corpo / no body)

Exemplo trabalhado nº 2: suponha um arquivo CSS de 45 KB, ou seja, 46.080 bytes (45 × 1.024). Na primeira visita, o cliente baixa os 46.080 bytes e guarda o ETag "9f8a1c-b3d0". Na recarga, ele envia If-None-Match com esse valor. Se nada mudou, o servidor responde 304 devolvendo só os cabeçalhos, cerca de 180 bytes, sem corpo. Em vez de 46.080 bytes, trafegam 180: uma economia de 45.900 bytes (46.080 − 180), ou 99,6% (45.900 ÷ 46.080). Multiplique isso por dezenas de recursos por página e milhares de visitas, e o 304 vira uma das maiores alavancas de performance da web.

Dois detalhes fecham o assunto. Primeiro, um 304 nunca carrega corpo, se um proxy ou framework devolve conteúdo num 304, algo está errado. Segundo, ETags vêm em duas formas: forte (o conteúdo é idêntico byte a byte) e fraca (prefixo W/, o conteúdo é equivalente o suficiente). A fraca é útil quando compressão ou espaços em branco variam sem mudar o significado. Em ambos os casos, é o servidor que decide se o validador ainda vale.

5xx: o outro lado falhou, 500 vs 503 e o 429 no meio

No 5xx o problema é do servidor, mas reconhecer qual código apareceu direciona o debug. O 500 Internal Server Error (§15.6.1) é o genérico, quase sempre uma exceção não tratada; a resposta útil está no log, não no número. O 502 Bad Gateway e o 504 Gateway Timeout envolvem um proxy: o 502 é resposta inválida do serviço de trás (a app caiu), o 504 é o proxy sem resposta a tempo (a app travou). E o 503 Service Unavailable (§15.6.4) é o mais honesto da família.

A diferença prática entre 503 e 500 é o que o cliente deve fazer. O 500 não promete nada, pode ser um bug permanente. O 503 diz “estou fora agora, volte depois” e pode anexar o header Retry-After (RFC 9110 §10.2.3) indicando quando tentar de novo. Esse mesmo header aparece no primo do 4xx que sinaliza excesso: o 429 Too Many Requests (RFC 6585 §4). Ao estourar um rate limit, um servidor bem-educado responde 429 e sugere no Retry-After quanto esperar; um cliente bem-educado obedece antes de tentar de novo.

Escolhendo o código certo (e os cantos curiosos)

Escolher o status certo é uma decisão de projeto, não um detalhe de última hora. O código é a primeira coisa que outro sistema lê, um proxy, um crawler, um cliente que decide se tenta de novo. Errá-lo é mentir para quem confia nessa leitura. Este checklist resolve a maioria dos casos:

• Movi uma página comum (GET) em definitivo? 301. É um endpoint de API que recebe POST? 308 (preserva o método).
• Desvio passageiro? 302. Se o método precisa sobreviver, 307.
• Falta login/token? 401, e nunca esqueça o header WWW-Authenticate. Logado mas barrado? 403.
• Página que não existe? 404. Removida de propósito? 410. Nunca 200 com “não encontrado” no corpo.
• Estourou o rate limit? 429 com Retry-After. Fora do ar por deploy/sobrecarga? 503 com Retry-After.
• Exceção inesperada no backend? 500, e vá direto ao log. Recurso em cache pode continuar válido? Emita ETag e responda 304 na revalidação.

Ler o status é só o começo; os cabeçalhos ao redor completam a história. Depois de acertar o código, vale auditar o resto da resposta: o analisador de headers de segurança dá uma nota aos seus headers, o inspetor de cookies destrincha as flags de Set-Cookie, e o verificador de links checa a segurança de uma URL antes de você abri-la. Juntos, eles transformam “que número foi esse?” em “o que a resposta inteira está dizendo?”.