500 Internal Server Error: causas, logs e como difere do 502

Por que o 500 diz tão pouco

A RFC 9110 define o 500 como uma condição inesperada que impediu o servidor de atender à requisição. Isso é deliberadamente amplo. Qualquer coisa que a aplicação não previu, de uma referência nula a uma conexão de banco de dados falhada a um arquivo de configuração que não consegue interpretar, acaba sob o mesmo número.

A vagueza também é um recurso de segurança. Uma página de 500 nunca deveria vazar stack traces, caminhos de arquivo, fragmentos de SQL ou versões de bibliotecas para o público, porque esses são exatamente os detalhes que um atacante quer. Então o código permanece genérico na resposta, e o detalhe vai para um log que só você pode ler. Essa troca está correta, e torna um conhecimento mais útil do que qualquer outro: onde os seus logs ficam.

500 versus 502, 503 e 504

Os quatro são erros de servidor, mas são produzidos por componentes diferentes e apontam para problemas diferentes. Acertar isso economiza a maior parte do tempo de depuração.

• 500 vem da própria aplicação. Algo rodou e lançou uma exceção. O log da aplicação tem um stack trace.
• 502 vem de um proxy na frente da aplicação, que recebeu uma resposta inválida ou uma conexão fechada do backend. O backend muitas vezes não registra nada, porque nunca terminou a requisição. Veja o guia do 502.
• 503 é uma recusa, não uma quebra. O servidor está sobrecarregado ou em manutenção e está recusando trabalho de propósito, geralmente com Retry-After.
• 504 é um timeout. O backend estava acessível mas não respondeu dentro do limite do proxy. A requisição muitas vezes ainda está rodando nos bastidores.

Um atalho direto: 500 significa que o seu código quebrou, 502 significa que o seu backend está morto ou se comportando mal, 503 significa que o seu servidor está dizendo não de propósito, 504 significa que o seu backend está lento demais. A família inteira é comparada na visão geral do 5xx.

O que causa um 500

• Exceções não tratadas no código da aplicação. A maior categoria individual. Um valor nulo, uma conversão de tipo falhada, um índice de array fora do intervalo, uma divisão por zero em um caminho que ninguém testou.
• Falhas de banco de dados. Pool de conexões esgotado, credenciais rotacionadas, o banco de dados reiniciou, uma consulta que trava (deadlock) ou dá timeout.
• Dependências ausentes ou quebradas depois de uma implantação. Um pacote que não instalou, um arquivo que o build não copiou, uma variável de ambiente que existe em staging e não em produção.
• Erros de sintaxe de configuração. No Apache, uma única diretiva inválida em um arquivo .htaccess produz 500 para toda requisição sob aquele diretório.
• Permissões e posse de arquivos. A aplicação não consegue ler um arquivo de configuração ou escrever em um diretório de cache, sessão ou upload.
• Limites de recursos. Um limite de memória, um limite de tempo de execução ou um disco cheio. Esses tipicamente produzem 500s intermitentes que acompanham o tráfego.
• Falhas de API de terceiros que o código chama sem um fallback, então uma indisponibilidade remota vira a sua página de erro.

Como diagnosticar um 500

1. Confirme o código e quem o produziu. Uma página de erro personalizada pode esconder o status real:

   curl -sS -o /dev/null -D - https://example.com/failing-page

   Verifique a linha de status e qualquer cabeçalho Server ou de CDN. Se o erro é assinado por uma rede de borda e a origem responde 200, você não está nem olhando para um 500 da sua aplicação.
2. Abra o log da aplicação primeiro. É aqui que está o stack trace. Logs do framework, o fluxo de log da plataforma ou o stdout do contêiner, o que a sua stack usar, e combine por timestamp e caminho da requisição.
3. Depois o log de erro do servidor web. O error_log do Apache, o error.log do nginx, ou o Log de Eventos do Windows para o IIS. Se a aplicação nunca registrou nada, a falha aconteceu antes de o seu código rodar, o que aponta para configuração ou o runtime.
4. Reproduza deliberadamente. Estabeleça se o 500 afeta uma URL, um método HTTP, um usuário ou tudo. Um 500 só em POST geralmente significa tratamento de formulário ou um caminho de escrita. Um 500 para um usuário geralmente significa os dados dele.
5. Ative erros detalhados em um ambiente não público. Nunca em produção. Reproduza em staging com a saída de erro completa, o que transforma um 500 genérico em uma linha específica.
6. Verifique o que mudou. A última implantação, um envio de configuração, uma renovação de certificado, uma atualização de dependência ou uma migração de banco de dados. Se o site estava bem há uma hora, a resposta quase sempre está na última mudança.
7. Verifique os recursos do host. Espaço em disco, memória e contagens de conexão. Um disco que encheu de logs produz 500s que parecem completamente não relacionados ao código.

Os 500s que só uma página devolve

A maioria dos 500s não tira o site inteiro do ar. Uma rota, um formulário ou uma região quebra enquanto a página inicial continua carregando, então nada parece errado de fora e os erros aparecem dias depois como cadastros perdidos. Uma verificação HTTP agendada nas páginas que importam, não só na página inicial, compara o código devolvido contra o esperado e alerta no momento em que uma rota começa a responder 500. Os alertas podem chegar por e-mail, SMS, chamada de voz, Slack, Telegram e mais, então uma falha noturna alcança quem está de plantão em vez de esperar pela manhã. A HostTracker monitora sites desde 2004.