Códigos HTTP e o que fazer
Do ponto de vista de operação, o que importa é: de quem é o problema e o que investigar primeiro.
As faixas
Seção intitulada “As faixas”| Faixa | Significado | De quem é |
|---|---|---|
| 1xx | Informativo | — |
| 2xx | Sucesso | — |
| 3xx | Redirecionamento | Configuração |
| 4xx | Erro do cliente | Cliente, ou contrato mal definido |
| 5xx | Erro do servidor | Seu — é o que entra no SLO |
Alerte sobre 5xx como proporção. 4xx alto costuma indicar problema de contrato, integração quebrada ou ataque — merece painel, raramente página.
2xx e 3xx
Seção intitulada “2xx e 3xx”| Código | Uso |
|---|---|
| 200 OK | Sucesso genérico |
| 201 Created | Recurso criado (devolva Location) |
| 202 Accepted | Aceito para processamento assíncrono |
| 204 No Content | Sucesso sem corpo (DELETE, PUT idempotente) |
| 301 / 308 | Movido permanentemente (308 preserva o método) |
| 302 / 307 | Temporário (307 preserva o método) |
| 304 Not Modified | Cache do cliente ainda válido |
Laço de redirecionamento costuma ser regra duplicada: aplicação e proxy forçando HTTPS ao
mesmo tempo. Diagnostique com curl -I sem -L.
| Código | O que investigar |
|---|---|
| 400 Bad Request | Payload inválido; veja o log da aplicação |
| 401 Unauthorized | Sem credencial, ou token expirado (autenticação) |
| 403 Forbidden | Autenticado, sem permissão (autorização) — ou WAF bloqueando |
| 404 Not Found | Rota errada, recurso removido, ingress sem regra |
| 405 Method Not Allowed | Método não suportado naquela rota |
| 408 Request Timeout | O cliente demorou a enviar |
| 409 Conflict | Conflito de estado (versão otimista) |
| 413 Payload Too Large | Limite de corpo no proxy ou no ingress |
| 415 Unsupported Media Type | Content-Type errado |
| 422 Unprocessable | Sintaxe ok, semântica inválida |
| 429 Too Many Requests | Limite de taxa; respeite Retry-After |
| 431 Headers Too Large | Cabeçalho grande demais (cookie inchado) |
Aumento súbito de 404 em rota específica costuma ser deploy que mudou caminho, ou ingress recém-alterado. Salto de 401/403 costuma ser rotação de credencial ou expiração de token.
| Código | Significado operacional | Primeiro passo |
|---|---|---|
| 500 | Erro não tratado na aplicação | Log e stack trace |
| 501 | Não implementado | Contrato |
| 502 | O proxy recebeu resposta inválida do backend | O backend caiu, reiniciou ou fechou a conexão |
| 503 | Serviço indisponível | Sem instância saudável, ou sobrecarga rejeitando |
| 504 | O backend não respondeu no tempo | Lentidão real; olhe latência e dependências |
| 507 | Sem espaço | Disco |
A distinção entre os três centrais é o que mais economiza tempo:
- 502 — houve conexão, e a resposta veio quebrada ou a conexão caiu no meio. Suspeitos: Pod reiniciando, aplicação encerrando sem drenagem, idle timeout do balanceador maior que o keep-alive do backend.
- 503 — não havia para quem mandar, ou o serviço recusou. Suspeitos: nenhum endpoint pronto, readiness falhando, limite de taxa, circuit breaker aberto.
- 504 — mandou e esperou até desistir. Suspeitos: consulta lenta, dependência externa, pool esgotado, timeout mal escalonado entre camadas.
kubectl get endpointslice -n <ns> # 503: há endpoints?kubectl logs -l app=loja -n <ns> --previous | tail -50 # 502: morreu por quê?kubectl top pods -n <ns> # 504: saturaçãoCódigos e sinalizações de proxy
Seção intitulada “Códigos e sinalizações de proxy”| Onde | Sinal | Significado |
|---|---|---|
| Envoy | UF |
Falha ao conectar no upstream |
| Envoy | UO |
Estourou o limite de conexões (overflow) |
| Envoy | UT |
Timeout do upstream |
| Envoy | NR |
Nenhuma rota configurada |
| nginx | upstream timed out |
504 |
| nginx | connect() failed |
502 |
| ALB | 502 com TargetConnectionErrorCount |
Backend fechou a conexão |
| ALB | 503 com HTTPCode_ELB_5XX |
Sem alvo saudável |
Distinga sempre erro do balanceador de erro do backend: são métricas separadas, e a diferença aponta o lado certo do problema.
Cabeçalhos úteis no diagnóstico
Seção intitulada “Cabeçalhos úteis no diagnóstico”| Cabeçalho | Para quê |
|---|---|
Retry-After |
Quando tentar de novo (429, 503) |
X-Request-Id / traceparent |
Correlacionar com log e trace |
Cache-Control, Age, X-Cache |
Entender se veio do cache |
X-Forwarded-For, X-Forwarded-Proto |
Origem real atrás de proxy |
Location |
Destino do redirecionamento |
Pegadinhas
Seção intitulada “Pegadinhas”- API que devolve 200 com
{"erro": ...}no corpo torna o SLO cego: o erro não aparece na métrica. - 499 (nginx) significa que o cliente desistiu — investigue a latência, não o cliente.
- 503 durante deploy costuma ser drenagem mal configurada, não falha da aplicação.
- 502 esporádico e sem padrão quase sempre é idle timeout desalinhado entre proxy e backend.
- 4xx de bot e varredura infla o gráfico; filtre por rota conhecida antes de concluir.