Erro 500, 502, 503 e 504: o que significam e como resolver

Erro 500 significa que o servidor do seu site sofreu uma falha interna: ele recebeu o pedido do visitante, tentou processar e algo quebrou do lado de lá. Os irmãos dele contam variações da mesma história: o 502 é um intermediário que não recebeu resposta válida do seu servidor, o 503 é um serviço lotado ou em manutenção, e o 504 é uma espera que estourou o tempo limite. Todos fazem parte da família 5xx, os erros do lado do servidor, ou seja: o problema (e a solução) está na sua mão, não na do visitante. Neste guia você entende o que causa cada código, como resolver e como ficar sabendo na hora em que ele aparece, antes de qualquer cliente.

Seu site é um restaurante (e o erro 500 é o prato caindo na cozinha)

Pensa numa sexta-feira à noite num restaurante cheio. Você senta, escolhe, faz o pedido. O garçom anota, leva para a cozinha e some. O que acontece dali para a frente decide se a noite termina bem ou vira história para contar.

Seu site funciona igualzinho. O visitante é o cliente na mesa, o navegador faz o pedido, e do outro lado quase sempre tem um garçom (o proxy ou CDN, tipo nginx ou Cloudflare) levando cada pedido até a cozinha, que é o seu servidor. Se o cliente pede um prato que não existe no cardápio, o erro é dele: essa é a família 4xx, onde mora o famoso 404. Agora, se o pedido está certo e mesmo assim não sai, o problema é da casa. Essa é a família 5xx:

Vamos um por um.

Erro 500: deu ruim na cozinha

O erro 500 (Internal Server Error) é o mais genérico de todos: o servidor sabe que algo deu errado, mas não diz o quê. É a cozinha devolvendo a comanda com um bilhete escrito "não deu".

As causas mais comuns, na ordem em que vale suspeitar:

• A última coisa que você mudou. Um deploy recente, um plugin ou tema atualizado (clássico no WordPress), uma dependência nova. Se o erro apareceu hoje, pense no que você mexeu ontem.
• Um arquivo de configuração quebrado. Um .htaccess com uma linha errada derruba o site inteiro.
• O banco de dados fora do ar. O código está certo, mas não tem com quem falar.
• Memória estourada. Comum em hospedagem compartilhada: o site cresceu e o plano ficou pequeno.

Como resolver? Olhe os logs do servidor (a resposta quase sempre está lá, com nome e sobrenome), reverta a última mudança, desative o plugin mais recente ou pergunte à hospedagem se algo mudou do lado deles. Regra de ouro: erro 500 quase nunca aparece do nada; alguma coisa convidou ele.

Erro 502: o garçom voltou de mãos vazias

Entre o visitante e o servidor quase sempre existe um intermediário: um proxy como o nginx, um CDN como o Cloudflare, o balanceador da sua hospedagem. O erro 502 (Bad Gateway) significa que esse intermediário está vivo e trabalhando, mas quando foi buscar a resposta na cozinha, não encontrou ninguém: sua aplicação caiu, está reiniciando ou respondeu algo que não dá para servir.

O que conferir:

• Sua aplicação ainda está de pé? Um processo que morre e não reinicia sozinho é a causa número um.
• Você acabou de fazer deploy? Muitos 502 duram exatamente o tempo que a aplicação leva para reiniciar.
• É a hospedagem ou o CDN? Confira a página de status deles antes de caçar fantasma no seu código.

Erro 503: casa lotada

O erro 503 (Service Unavailable) é o restaurante com a placa "volto já" na porta. O servidor existe, mas não consegue atender: ou está sobrecarregado ou está em manutenção.

É o único da família que às vezes é de propósito: muitos sites respondem 503 enquanto instalam uma atualização. O problema é quando ninguém planejou:

• Sua campanha deu certo demais. O tráfego da Black Friday, uma menção viral, e o servidor que aguentava 100 visitas recebe 10.000.
• O modo manutenção ficou ligado. A atualização terminou e ninguém tirou a placa da porta.
• Recursos no limite. Em hospedagem compartilhada, às vezes o vizinho de servidor faz festa e quem paga é você.

As soluções vão de colocar uma camada de cache ou CDN (para nem toda visita chegar até o servidor) a subir de plano de hospedagem antes da próxima campanha grande.

Erro 504: a cozinha que nunca responde

O erro 504 (Gateway Timeout) é primo do 502, com outra história: o intermediário encontrou o servidor, entregou o pedido e cansou de esperar a resposta. Seu servidor não morreu: está lento. Para o visitante, dá na mesma.

Os suspeitos de sempre:

• Uma consulta lenta no banco de dados. Aquela busca que demora 40 segundos desde que a tabela cresceu.
• Um serviço externo devagar. O gateway de pagamento ou uma API de terceiros engasgou, e o seu site é quem leva a fama.
• Um servidor que não dá mais conta. O plano contratado há três anos não aguenta o site de hoje.

A solução de verdade é descobrir o que está lento (os logs e as ferramentas da hospedagem ajudam), otimizar a consulta ou aumentar os recursos.

Como descobrir um erro 500 antes dos seus clientes

Agora a parte incômoda: erro de servidor não manda aviso prévio. Ele não aparece em horário comercial nem espera você estar olhando o site. Aparece às 2 da manhã, no pico de tráfego, ou bem no dia da campanha que você preparou o mês inteiro. E se você vive de loja virtual, cada minuto de erro é carrinho abandonado: vale conferir o que o monitoramento faz por um ecommerce.

A saída é não depender de sorte: um serviço de monitoramento visita seu site de tempos em tempos, como um cliente de verdade, e se o servidor responder com erro 500, 502, 503 ou 504, marca o site como fora do ar e te avisa na hora. O OhSnap, por exemplo, verifica seu site em intervalos de até 30 segundos e, antes de alertar, faz uma dupla verificação, para uma oscilação de rede não te acordar à toa. Os alertas chegam por email, SMS e, no plano Unlimited, por WhatsApp, Slack ou Telegram: todos os canais estão na página de alertas.

E enquanto você conserta o problema, uma página de status pública conta aos seus usuários o que está acontecendo, antes de o "caiu?" lotar o seu suporte.

Comece antes do próximo susto

Você não precisa de orçamento para parar de descobrir os problemas por acidente: o plano gratuito do OhSnap inclui 5 monitores com verificações a cada 5 minutos e alertas por email e SMS sem pagar nada. Erro de servidor, mais cedo ou mais tarde, acontece com todo mundo; até os sites gigantes deixam o prato cair de vez em quando. A diferença entre um sufoco e uma crise é quem fica sabendo primeiro. Que o print do erro 500 nunca chegue até você mandado por um cliente.