Erros de servidor HTTP 5xx: significado, diagnóstico e correções

O que este erro significa e como reconhecê-lo

Você pode observar um ou mais destes sintomas:

• Um site ou uma API retorna um status HTTP de 500 a 599.
• A resposta é um erro genérico do servidor, um erro do aplicativo ou uma página personalizada de reverse proxy, load balancer ou CDN.
• Apenas uma rota, operação ou endpoint de API falha, enquanto as outras páginas continuam funcionando.
• Todo o serviço fica indisponível ou retorna erros de forma intermitente.
• As solicitações ficam lentas antes de terminar com um 504 ou outra resposta 5xx relacionada a gateway.
• A resposta inclui um ID de solicitação, identificador upstream ou cabeçalho de erro específico do servidor que pode ajudar a identificar a camada geradora.

Causas principais, por probabilidade

As causas prováveis, das mais comuns às menos comuns, incluem:

1. Exceções do aplicativo ou falhas no tratamento da solicitação. Erros não tratados no aplicativo, caminhos de entrada inválidos ou uma alteração de código defeituosa podem produzir uma resposta 500.
2. Alterações recentes de deployment ou configuração. Um release, uma alteração em variável de ambiente, uma mudança de roteamento ou um erro de configuração do servidor pode afetar uma rota ou todo o serviço.
3. Processos de backend não saudáveis. Um processo do aplicativo parado, em crash, sobrecarregado ou inacessível pode fazer um proxy retornar 502 ou 503.
4. Falhas de dependências. Erros de banco de dados, serviços internos indisponíveis, serviços externos lentos ou pools de conexão esgotados podem aparecer como vários códigos 5xx diferentes.
5. Timeouts entre camadas. Um gateway pode retornar 504 quando um serviço upstream não responde dentro do tempo limite configurado; dependências lentas podem ser a causa subjacente.
6. Pressão sobre os recursos. Uso elevado de CPU ou memória, saturação de workers, esgotamento de espaço em disco ou limites de conexão podem tornar um serviço indisponível ou fazer as solicitações expirarem.
7. Manutenção ou proteção intencional. Um serviço pode retornar 503 durante manutenção, drenagem de tráfego, limitação de taxa ou proteção contra sobrecarga.
8. Comportamento específico da camada. O mesmo incidente subjacente pode produzir códigos diferentes dependendo de o aplicativo, servidor web, reverse proxy, load balancer ou CDN ter gerado a resposta.

Como corrigir

1. Registre a falha com precisão

Registre o código de status exato, a URL ou operação de API afetada, o horário incluindo o fuso horário, a frequência, o corpo da resposta e os cabeçalhos de resposta relevantes. Preserve qualquer ID de solicitação ou trace ID. Se você estiver apenas acessando o site, envie esses detalhes ao responsável pelo serviço em vez de alterar as configurações do servidor.

2. Identifique a camada que gerou a resposta

Compare a página de erro ou o corpo JSON, os cabeçalhos, os cookies e os identificadores do servidor com uma resposta conhecida como bem-sucedida. Um corpo de erro específico do framework pode apontar para o aplicativo; uma página personalizada do gateway ou da CDN pode significar que a solicitação falhou antes que a origem produzisse uma resposta. Verifique os logs do reverse proxy, load balancer ou CDN quando os logs da origem não contiverem uma solicitação correspondente.

3. Diferencie uma indisponibilidade ampla de uma falha específica de rota

Teste um endpoint de health check aprovado e de baixo impacto, além de uma rota conhecida por estar funcionando. Se apenas uma rota falhar, examine o código do aplicativo, o acesso aos dados e as dependências específicas da solicitação. Se todas as rotas falharem, priorize a saúde dos processos, o estado do deployment, o roteamento, a capacidade e as dependências compartilhadas. Não recarregue repetidamente um endpoint de produção como substituto de um health check.

4. Correlacione os logs no mesmo horário

Analise em conjunto os logs do aplicativo, do servidor web, do proxy/load balancer e das dependências. Procure primeiro pelo ID de solicitação e, em seguida, restrinja a busca pelo horário e pelo endpoint. Procure stack traces, reinicializações de processos, mensagens de conexão recusada, códigos de status upstream, mensagens de timeout, chamadas de banco de dados malsucedidas e conexões rejeitadas. Remova credenciais, tokens e dados confidenciais das solicitações antes de compartilhar os logs.

5. Verifique alterações recentes e a integridade do serviço

Analise deployments, feature flags, alterações de configuração, atualizações de certificados ou roteamento, atividades de manutenção e mudanças nas dependências realizadas pouco antes do início das falhas. Confirme que os processos de backend estão em execução e passando nos health checks. Se uma alteração recente tiver forte correlação com o incidente, use o procedimento de rollback aprovado pelo serviço e obtenha a autorização necessária; não reinicie nem faça rollback de sistemas de produção sem aprovação operacional.

6. Verifique as dependências e a pressão sobre os recursos

Inspecione a conectividade e a latência do banco de dados, a integridade dos serviços internos, as respostas das dependências externas, o uso do pool de conexões, a profundidade das filas, a CPU, a memória, o espaço em disco, a disponibilidade de workers e os limites de conexão. Uma dependência apenas lenta pode causar um 504 mesmo quando o processo do aplicativo está em execução. Corrija o componente limitado ou com falha, em vez de mascarar o sintoma aumentando timeouts indiscriminadamente.

7. Use o código de status para direcionar a investigação

• 500 Internal Server Error: Comece pelos logs do aplicativo, pelos erros do servidor, pela rota com falha e por alterações recentes de código ou configuração.
• 502 Bad Gateway: Inspecione a conexão entre o proxy e o upstream, além da resposta do upstream. Verifique se o backend está inativo, encerrando conexões, retornando dados malformados ou sendo acessado por uma rota incorreta.
• 503 Service Unavailable: Verifique o estado de manutenção, os health checks ou verificações de prontidão, os controles de sobrecarga, a disponibilidade dos processos e as dependências compartilhadas.
• 504 Gateway Timeout: Meça onde o tempo está sendo gasto. Verifique a latência do upstream, as chamadas ao banco de dados ou externas, os pools de conexão e as configurações de timeout em cada camada.
• Outros status 5xx: Use a definição exata do status e o componente que o emitiu; não presuma que toda resposta 5xx tenha a mesma causa.

8. Aplique a correção autorizada mais específica e verifique com segurança

Corrija o problema identificado no aplicativo, na configuração, na dependência ou na capacidade usando o processo de controle de mudanças do ambiente. Depois, verifique um endpoint simples de health check, a operação que falhou anteriormente e funções dependentes representativas. Confirme que as taxas de 5xx e a latência voltaram ao normal sem criar gravações duplicadas ou carga adicional. Se a correção envolver uma ação que altere o estado, como reiniciar um processo, drenar tráfego ou alterar um timeout, documente o impacto esperado e obtenha autorização antes.

Prevenção e como verificar a correção

• Monitore a taxa de 5xx, a latência e a disponibilidade por rota, serviço e camada que gera a resposta.
• Use verificações de prontidão e liveness que reflitam os requisitos reais das dependências sem criar carga excessiva.
• Mantenha IDs de solicitação ou trace IDs consistentes entre proxies, aplicativos e dependências.
• Defina timeouts e limites de conexão limitados e revisados em cada fronteira de serviço; evite que chamadas externas lentas consumam todos os workers.
• Configure alertas para saturação de recursos, crashes de processos, latência do banco de dados, esgotamento do pool de conexões e pressão sobre o disco antes que se tornem falhas generalizadas.
• Use deployments graduais, mudança de tráfego baseada em health checks e um procedimento de rollback testado.
• Documente quais códigos 5xx cada proxy, aplicativo e dependência pode emitir para que a equipe não trate 500, 502, 503 e 504 como equivalentes.
• Teste regularmente o comportamento diante de dependências degradadas e sobrecarga em um ambiente autorizado.

Perguntas frequentes