1. Significado
O 500 é um erro genérico: o servidor encontrou uma condição inesperada e não conseguiu atender. Para quem visita o site, não há muito o que fazer; para quem mantém, a pista está nos logs.
2. Onde olhar primeiro
# Servidor web
sudo tail -n 100 /var/log/nginx/error.log
sudo tail -n 100 /var/log/apache2/error.log
# Aplicação como serviço
journalctl -u minha-api -n 100 --no-pager
docker logs --tail 100 api
Procure a primeira exceção ou “stack trace” no horário do erro. Ferramentas como tail e journalctl ajudam a acompanhar enquanto reproduz.
3. Causas mais comuns
- Exceção não tratada no código (valor nulo, JSON inválido, divisão por zero).
- Variável de ambiente ausente ou segredo errado em produção.
- Banco de dados inacessível, migração não aplicada, esgotamento do pool de conexões.
- Permissões de arquivo (a aplicação não pode gravar em uploads ou cache). Veja chmod.
- Configuração do servidor:
.htaccessinválido no Apache, bloco inválido no Nginx, versão de runtime incompatível. - Disco ou memória esgotados: confira df e a página do OOM killer.
4. Como depurar com segurança
- Reproduza com
curl -ipara ver cabeçalhos e corpo exatos. - Compare staging e produção (versões, variáveis, dados).
- Reverta o deploy mais recente se o erro começou logo depois dele.
- Não ative modo debug em produção: stack traces expõem caminhos, queries e, às vezes, segredos.
5. Melhorando a resposta ao usuário
Devolva uma página de erro amigável, registre um identificador da requisição (request id) e mostre-o ao usuário para facilitar o suporte. Envie os erros para uma ferramenta de monitoramento e alerte quando a taxa de 500 subir.
Continue explorando
← erros · 504 · 502 · tail · Observabilidade
Veja também o hub de conteúdo, o glossário e os cursos gratuitos.