Códigos de Status HTTP e Troubleshooting

Códigos de status HTTP são códigos de resposta de três dígitos que servidores retornam para comunicar o resultado de requisições. Em sistemas distribuídos, interpretá-los corretamente exige entender o caminho completo da requisição: cliente, CDN, balanceador de carga, servidor de aplicação e dependências upstream.

Como os códigos de status se comportam em sistemas distribuídos

Uma única requisição atravessa múltiplos componentes antes de chegar à origem. Cada componente contribui ou modifica o código de status retornado ao cliente.

Cliente ──► CDN ──► Balanceador ──► Aplicação ──► Banco de Dados
  │          │           │               │              │
  │     Intercepta   Roteia para     Processa      Pode expirar
  │     4xx/5xx     nó saudável     requisição     ou falhar
  │     da origem                   e retorna
  │                                 200/4xx/5xx

Nesta arquitetura, o código de status que o cliente vê pode vir de qualquer camada. Um 502 Bad Gateway do CDN significa que a origem retornou uma resposta inválida. Um 504 Gateway Timeout significa que a origem não respondeu dentro da janela de timeout configurada.

Fluxo de troubleshooting

         ┌─────────────────────────────┐
         │  Identifique o código       │
         └──────────┬──────────────────┘
                    ▼
         ┌─────────────────────────────┐
         │  Classe: 4xx ou 5xx?        │
         └──────────┬──────────────────┘
                    ▼
         ┌─────────────────────────────┐
    ┌────┤  Quem gerou?                │
    │    │  - Logs de borda do CDN     │
    │    │  - Logs de acesso da origem │
    │    └──────────┬──────────────────┘
    │               ▼
    │    ┌─────────────────────────────┐
    │    │  Reproduza a requisição     │
    │    │  Isole variáveis:           │
    │    │  - Headers                  │
    │    │  - Método                   │
    │    │  - Corpo                    │
    │    │  - Autenticação             │
    │    └──────────┬──────────────────┘
    │               ▼
    │    ┌─────────────────────────────┐
    │    │  Verifique dependências:    │
    │    │  - API upstream             │
    │    │  - Banco de dados           │
    │    │  - Cache                    │
    │    └──────────┬──────────────────┘
    │               ▼
    │    ┌─────────────────────────────┐
    └────┤  Aplique correção e verifique│
         └─────────────────────────────┘

Padrões de código de status por camada

Camada	Códigos comuns	Significado
CDN	502, 504, 403	Origem inacessível, timeout de origem, bloqueio WAF
Balanceador	503, 502, 504	Sem upstream saudável, resposta inválida do upstream, timeout
Aplicação	200, 201, 400, 401, 403, 404, 409, 422, 429, 500	Resultado do processamento
Autenticação	401, 403	Credenciais ausentes, permissões insuficientes
Banco de dados	500, 503 (propagado)	Falha de query, pool de conexões esgotado
API upstream	502 (propagado como 502 ou mapeado)	Falha de dependência

Diagnósticos principais para cada código de status

Padrões 4xx:

400: Inspecione formato do corpo da requisição, headers obrigatórios, tipos de parâmetros
401: Verifique header Authorization, expiração de token, formato do token
403: Verifique permissões para o recurso e método específicos
404: Confirme que o caminho da URL corresponde exatamente à definição da rota (barras, maiúsculas/minúsculas)
405: Verifique método HTTP contra métodos permitidos para o endpoint
409: Verifique modificações concorrentes, chaves de idempotência
422: Valide contra regras de negócio, não apenas restrições de esquema
429: Verifique header Retry-After, avalie configuração de limite de taxa

Padrões 5xx:

500: Verifique logs do servidor para exceções não tratadas. Confirme se nenhum deployment recente introduziu problemas.
502: Verifique logs do servidor upstream. Garanta que o upstream retorna respostas HTTP válidas.
503: Verifique deployment em andamento, picos de tráfego, exaustão de recursos
504: Verifique tempo de resposta do upstream. Ajuste configuração de timeout se o upstream for lento mas confiável.

Métricas e Medição

Tempo até o primeiro byte (TTFB): Tempo até os headers de resposta chegarem (meta: <500ms p95 para conteúdo dinâmico)
Taxa de consumo de error budget: Percentual de erros 5xx permitidos consumidos ao longo do tempo (meta: <10% do error budget por dia)
Distribuição de códigos de status: Percentual de cada código de resposta sobre o total de requisições

Referências do setor:

Taxas de 5xx acima de 0,1% exigem investigação (diretrizes Google SRE)
TTFB médio para respostas em cache na borda: 20-50ms (benchmarks de provedores CDN, 2025)
TTFB médio para respostas não cacheadas da origem: 200-800ms (HTTP Archive, 2025)

Erros Comuns e Correções

Erro: Tratar todos os erros 5xx como bugs de aplicação Correção: Classifique erros 5xx por camada (CDN, balanceador, aplicação, upstream). Um 504 é tipicamente um problema de infraestrutura, não de código.

Erro: Não registrar contexto suficiente com códigos de status Correção: Registre ID da requisição, ID do usuário, endpoint, método, tempo de resposta e código de status upstream junto com cada resposta.

Erro: Misturar budgets de erro de 4xx e 5xx Correção: Erros 4xx indicam mau comportamento do cliente e não devem consumir budgets de erro do servidor. Monitore 4xx e 5xx independentemente.

Erro: Ignorar respostas 429 no código cliente Correção: Implemente backoff exponencial e respeite headers Retry-After em todos os clientes.

Erro: Tratar 502 e 503 da mesma forma Correção: 502 significa resposta inválida do upstream. 503 significa que o serviço em si está indisponível. Cada um requer um caminho de diagnóstico diferente.

Casos de uso de troubleshooting

Resposta a picos de tráfego

Quando uma campanha de marketing gera tráfego inesperado, respostas 503 e 429 aumentam. Verifique configuração de auto-scaling, limites de taxa e taxa de acerto de cache do CDN. Aumente TTL de cache para ativos estáticos como mitigação de curto prazo.

Rollback de deployment

Um novo release introduz erros 500. Compare taxas de erro antes e depois do deployment usando logs de requisição. Se a taxa de 5xx aumentar 2x ou mais, reverta e investigue o diff.

Dependência de API de terceiros

Uma API parceira upstream retorna 503. Seu serviço pode retornar 502 ou 503 para os clientes. Implemente circuit breakers e respostas de fallback para evitar falhas em cascata.

Compatibilidade com aplicativo mobile

Uma atualização do iOS envia um novo header que seu servidor não espera, causando erros 400 para um subconjunto de usuários. Registre headers e corpo da requisição para cada resposta 4xx para detectar desvios de contrato de API.

Perguntas Frequentes

Como distinguir entre um 502 gerado pelo CDN e um 502 gerado pela origem? Verifique logs de acesso do CDN e logs de acesso da origem simultaneamente. Se os logs da origem mostram a requisição com resposta não 5xx, o CDN gerou o 502. Se os logs da origem mostram um 5xx ou estão ausentes (timeout), a origem causou.

O que significa um 503 durante um deployment? Significa que o balanceador de carga marcou a instância como não saudável enquanto ela iniciava. Garanta que verificações de saúde retornem 200 apenas após a aplicação estar totalmente inicializada, não imediatamente após o processo iniciar.

Como rastrear um código de status através de múltiplos serviços? Use um correlation ID propagado através de headers. Cada serviço registra o código de status que retorna junto com o correlation ID. Agregue logs por correlation ID para ver a cadeia completa.

Devo tentar novamente após uma resposta 429? Sim, mas apenas após o atraso especificado no header Retry-After. Implemente jitter e backoff exponencial para evitar tempestades de repetição.

Por que meu balanceador retorna 503 quando a aplicação está saudável? Verifique a configuração da verificação de saúde. O balanceador pode usar uma porta, caminho ou protocolo diferente da aplicação. Garanta que o endpoint de saúde retorne 200 dentro do timeout.

Qual é a diferença entre 502 e 504 no contexto de CDN? 502 significa que o CDN recebeu uma resposta malformada da origem. 504 significa que a origem não respondeu dentro do timeout configurado do CDN. Ambos indicam problemas de origem mas requerem correções diferentes de timeout ou validação de resposta.

Como depurar erros 5xx intermitentes? Execute a mesma requisição múltiplas vezes e compare respostas. Se 5xx ocorre aleatoriamente, verifique exaustão de recursos (pools de conexão, threads, conexões de banco de dados) ou pausas de garbage collection usando ferramentas de profiling da aplicação.

Qual código de status retornar quando uma dependência está fora do ar? Retorne 502 Bad Gateway. Não mascare como 500 ou 503. 502 sinaliza corretamente que o erro se originou de uma dependência, não do serviço em si.

Como configurar alertas de monitoramento para códigos de status? Alerta para taxa de 5xx acima de 0,1% em 5 minutos. Alerta para taxa de 4xx acima de 10% do total de requisições. Alerta para quedas súbitas na taxa de 2xx. Defina alertas separados para cada endpoint crítico.

Qual é a relação entre códigos de status e SLIs? Códigos de status são uma entrada direta para SLIs de disponibilidade. Conte 5xx e 4xx apropriados (timeouts) como falha. Divida respostas bem-sucedidas pelo total de requisições para calcular disponibilidade. Use isso para acompanhar conformidade com SLOs.

Como isso se aplica na prática

Em sistemas de produção, um único código de status raramente conta a história completa. O mesmo 502 pode significar um timeout de origem, uma resposta inválida do upstream ou uma má configuração do CDN. Rastrear o código através do sistema importa mais do que reconhecê-lo.

Equipes que lidam efetivamente com resposta a incidentes mantêm runbooks para cada padrão de código de status. Esses runbooks especificam quais logs verificar primeiro, quais métricas comparar e quais ações tomar com base no padrão. Isso reduz o tempo médio de resolução de horas para minutos.

Como implementar na Azion

A Azion fornece ferramentas para rastrear códigos de status através do caminho completo da requisição:

Edge Logs: Exporte logs em tempo real via Azion Data Streaming para ver códigos de status em cada camada
Application Analytics: Use Azion Metrics para filtrar por classe de código de status e identificar padrões anômalos
Configuração de Resposta de Erro: Personalize respostas 4xx e 5xx retornadas pela borda da Azion, incluindo dicas de retry
Regras de Alerta: Configure alertas baseados em limiares para taxas de 5xx com granularidade por aplicação

Saiba mais na Documentação da Azion.

Fontes:

IETF. “HTTP Semantics.” RFC 9110. 2022.
Google SRE. “Service Level Objectives.” 2023.
HTTP Archive. “Web Almanac.” 2025.
AWS. “Troubleshooting 5xx Errors.” 2025.

Entre em nossa comunidade