Erros 500: como identificar e corrigir

Por que um site apresenta erros 500 e como corrigir: um guia prático de triagem

Um erro 500 é o tipo de problema que faz um site parecer quebrado sem explicar o motivo. O navegador exibe uma mensagem seca, o visitante encontra um beco sem saída e a falha real geralmente está em outro lugar. É por isso que entender por que um site apresenta erros 500 e como corrigir vira um exercício de triagem, não um jogo de adivinhação.

Comece com uma regra: não presuma que toda página de erro feia seja um verdadeiro 500 do lado do servidor. Um 502, um 503, um timeout no gateway ou uma página de proxy personalizada do Cloudflare podem parecer próximos o bastante para confundir até equipes experientes. Rotular errado custa tempo.

1. Confirme se o erro é realmente um 500 do lado do servidor

Abra a página em uma janela anônima e observe a mensagem exata. Entender o que significa erro 500 internal server error ajuda a separar uma falha genérica de uma resposta específica da infraestrutura. Um erro de origem simples costuma dizer “500 Internal Server Error” ou algo igualmente genérico, enquanto uma camada de proxy pode mostrar seu próprio código, um ID de solicitação ou uma mensagem sobre o servidor upstream. Essa pequena diferença importa, porque um 502 geralmente aponta para uma resposta ruim do gateway, enquanto um 503 costuma significar que o serviço está temporariamente indisponível.

Verifique a resposta por pelo menos 2 caminhos: o navegador e uma requisição pela linha de comando, se você tiver uma. Se a página do navegador diz 500, mas o servidor na borda realmente retorna 502, você pode estar perseguindo o sistema errado. A solução muda conforme a origem.

Cloudflare, Fastly, nginx, Apache e sua aplicação podem registrar a falha de maneiras diferentes. Um site pode exibir uma página refinada do CDN com rótulo 5xx, enquanto outro devolve uma tela branca sem adornos e uma linha curta no corpo HTML. Mesmo sintoma, origem diferente.

2. Reproduza o erro de forma controlada

Teste a URL exata que falha, não apenas a página inicial. Um 500 em /checkout pode ser causado por um campo de formulário, um hook de plugin ou uma regra de rota, enquanto a página principal funciona normalmente. Se o problema aparece só em 1 URL, sua busca fica muito mais focada.

Repita a requisição variando 3 fatores: navegador, dispositivo e horário. Se falha no Chrome no desktop, mas não no Safari no celular, você pode estar vendo um caminho de script ou um caso-limite de cache. Se só falha depois de uma importação de newsletter ou às 2h da manhã, o próprio horário já é uma pista.

Torne o teste previsível. Uma requisição, uma mudança, um resultado. Depois tente a mesma URL com um estado diferente de login, porque usuários autenticados às vezes acionam caminhos de código que visitantes nunca tocam. Isso é especialmente comum em sites com painéis administrativos ou áreas de membros.

Guarde um registro simples: URL, horário, ação e resposta. Quatro campos bastam. Quando você tiver 3 ou 4 entradas, os padrões começam a aparecer.

3. Verifique o log de erros do servidor web em busca do primeiro ponto de falha

O log de erros costuma ser o primeiro lugar a olhar depois que a página falha duas vezes. Saber como verificar logs de erro do servidor ajuda a encontrar a causa antes que o problema se espalhe. Compare o horário do 500 com a entrada mais próxima no log e leia a linha anterior e a seguinte. A primeira linha costuma dizer mais do que a página de erro jamais dirá.

Você está procurando um nome de script, um módulo, um aviso de permissão ou um timeout no upstream. Um erro fatal do PHP pode nomear o arquivo diretamente. Um erro do servidor web pode mencionar um diretório ausente, um alvo de rewrite incorreto ou uma conexão negada com um processo backend.

Um hábito útil: copie o horário exato da requisição com falha e compare com os logs de acesso e de erro. Se o site estiver movimentado, o evento “mais próximo” ainda pode estar a alguns segundos de distância, então confira também o caminho da requisição e o código de status. Um único ID de requisição, se sua pilha adicionar um, pode economizar uma longa busca.

Quando o log nomeia um plugin, biblioteca ou módulo, pare um instante aí. Leia o contexto ao redor. Uma linha sobre “allowed memory size exhausted” aponta para limite de recursos, enquanto “permission denied” aponta para problema de propriedade ou modo, mesmo que ambos apareçam como 500.

4. Procure gatilhos de limite de recursos e timeout

Erros 500 muitas vezes aparecem quando o servidor fica sem algo básico. Memória é um deles. Tempo de execução é outro. Slots de workers são um terceiro. Quando qualquer um desses recursos satura, a requisição pode falhar antes de a página terminar de montar.

A falta de memória no PHP é um caso clássico. Uma exportação de relatório, o redimensionamento de imagens ou uma importação de produtos pode exigir mais memória do que o processo tem disponível, e o resultado pode ser um 500 em vez de um aviso elegante. Se a falha começa em requisições grandes e some quando a carga cai, esse é um forte suspeito.

Verifique também os limites de tempo de execução. Um script que fica em loop por tempo demais pode estourar o timeout e deixar o servidor limpando a bagunça. Isso pode acontecer durante jobs de importação, tarefas cron ou uma chamada lenta de API que espera outro serviço. Basta uma dependência lenta.

A saturação de workers ou processos é mais fácil de passar despercebida porque o site pode parecer saudável com pouco tráfego. Então 20 requisições chegam de uma vez, a fila enche e novas requisições começam a falhar. Alguns planos de hospedagem também impõem limites por conta de CPU, processos de entrada ou I/O, então o problema pode estar no plano, não no código.

Se sua pilha tiver monitoramento, verifique se os 500 aumentam junto com picos de tráfego. Um 500 que aparece só durante uma campanha, um release ou uma janela de backup geralmente é um problema de carga com outro nome. É aqui que o que mudou no monitoramento de sites após pode ajudar a definir o tipo de alerta que você precisa a seguir.

5. Verifique permissões de arquivos e pastas fora do CMS

Nem todo 500 vem da aplicação. Arquivos podem passar a pertencer ao usuário errado depois de um deploy, uma sincronização ou uma migração. As permissões de pasta também podem sair do controle. Basta mudar o modo de um diretório para bloquear gravações em cache, logs ou uploads e disparar uma falha na hora da requisição.

Confira primeiro os lugares que costumam ser esquecidos: uploads, arquivos temporários, arquivos de configuração, artefatos de deploy e diretórios de log. Se um desses caminhos não puder ser escrito pelo usuário do servidor web, o site pode falhar assim que tentar gravar um arquivo de sessão ou criar uma entrada de cache. É um problema pequeno com um resultado barulhento.

Problemas de propriedade são especialmente comuns após migrações de um host para outro. Um arquivo pode ter os bits de permissão corretos, mas o proprietário errado, o que ainda bloqueia o processo. É esse tipo de detalhe que faz um 500 parecer irracional até você olhar fora do CMS e inspecionar diretamente a camada do servidor.

Não “corrija” permissões abrindo tudo demais. Um chmod 777 rápido pode esconder o problema, mas também cria uma bagunça de segurança e, em geral, mascara a incompatibilidade real de propriedade. Se você precisar de uma base de segurança para o servidor depois de mudanças, vale manter por perto a orientação mais ampla de segurança do site enquanto testa.

6. Inspecione mudanças recentes no servidor ou no deploy

Volte 1 deploy, 1 mudança de host ou 1 edição de configuração. Os 500 costumam surgir logo após uma alteração de versão do PHP, um rewrite no servidor web, uma nova regra de redirect ou uma atualização de tarefa cron. Se o problema começou depois de uma migração, a própria migração pode ser o gatilho.

Saltos de versão do PHP podem expor código antigo que antes funcionava sem reclamar. Um módulo que funcionava em uma versão pode falhar em outra. O mesmo vale para diretivas do servidor web que eram aceitas no mês passado, mas agora geram erro quando o servidor lê a configuração. Uma única linha pode causar o estrago.

Regras de segurança são outra causa frequente. Uma regra de WAF, uma nova condição de firewall ou uma mudança de hardening do servidor pode bloquear uma requisição que parece suspeita, mesmo quando é legítima. É aqui que ter um log de mudanças supera a memória todas as vezes, porque as pessoas costumam esquecer a atualização “pequena” que quebrou a rota.

Se houve deploy, compare a versão mais recente que funcionava com a atual. Revise primeiro 3 coisas: arquivos de configuração, regras de roteamento e qualquer novo job em segundo plano. Muitas vezes o problema não está no recurso que você entregou, mas no efeito colateral que veio junto.

7. Restaure o serviço com o menor rollback seguro

O rollback deve ser pontual. Desative primeiro a mudança mais recente do lado do servidor, não o sistema inteiro. Reverta um arquivo de configuração, uma regra ou uma etapa do deploy por vez para enxergar qual ação restaura o site. Se você desfizer tudo de uma vez, perde a pista.

Comece pelo item menos arriscado que mudou por último. Se uma nova regra de redirect apareceu 20 minutos antes da falha, comente-a e teste novamente. Se um ajuste de PHP foi alterado, volte apenas essa configuração para o valor anterior e confira de novo. O objetivo é restaurar o serviço, não fazer uma limpeza dramática.

Para deploys de código, mantenha uma cópia segura pronta e faça rollback apenas da release afetada. Para configuração do servidor, salve o arquivo atual antes de editar para poder comparar linha por linha. Isso parece básico porque é básico mesmo, e o básico evita as paradas mais longas.

Às vezes o menor rollback seguro nem é técnico. Se uma tarefa cron estiver sobrecarregando o servidor a cada 5 minutos, pause o job e observe o site. Se um script de backup estiver consumindo recursos, ajuste o agendamento antes de mexer na aplicação. O site não se importa por que o servidor está cansado.

8. Evite que o mesmo 500 volte a acontecer

Configure monitoramento de logs para que o primeiro 500 repetido apareça antes de os clientes reclamarem. Um erro isolado é uma coisa. Cinco seguidos na mesma rota formam um padrão. Faça o alerta apontar para a rota, o horário e o texto do erro.

Teste os deploys em staging antes de colocá-los em produção. Uma cópia de staging detecta edições ruins de configuração e incompatibilidades de versão que, de outro modo, atingiriam o tráfego real primeiro. Mantenha a pilha o mais próxima possível da produção, porque uma configuração que parece inofensiva em um ambiente de teste pode falhar no real.

Registre mudanças em um só lugar. Isso inclui edições de configuração, atualizações de plugins, mudanças de PHP, ajustes de cron e alterações de regras de segurança. Se você já está mapeando mudanças no site, o blog da ostohlo tem material relacionado em ostohlo स्टूडियो ब्लॉग, o que pode ser útil quando você precisa de um registro em vez de memória.

Alertas importam mais quando se repetem. Se a mesma resposta 500 voltar após cada deploy ou cada pico de tráfego, aumente o rigor da revisão e mantenha uma nota curta do incidente com 3 fatos: o que mudou, onde falhou e o que corrigiu. Essa nota vira sua resposta mais rápida da próxima vez, especialmente quando a próxima falha acontecer durante uma janela de deploy que você não esperava.