Erro 500, 502, 503: o que significa cada código

Quando um site se parte, o reflexo é abrir o código. O código de erro apresentado é uma pista mais rápida: diz que camada cedeu, e os três mais comuns apontam para três reparações completamente diferentes. Cinco minutos de leitura aqui poupam uma hora de procura no sítio errado.

Os três códigos, numa tabela

O 504 não está no título e acompanha os outros tantas vezes que merece a sua linha: é o único dos quatro que indica lentidão em vez de paragem.

500: a aplicação rebentou

O servidor está de pé e respondeu. É o seu código que não chegou ao fim.

As três causas que mais se repetem:

• Um erro fatal depois de um deploy: uma dependência em falta, uma versão de linguagem diferente, um ficheiro de configuração ausente.
• A base de dados já não responde: serviço parado, ligações esgotadas, palavra-passe alterada e não propagada.
• O disco está cheio. É a causa mais subestimada, porque não se parece com nada: as sessões deixam de ser escritas, os registos também, e a aplicação tropeça em erros incoerentes.

Onde ver: o registo da aplicação, ao minuto em que o erro apareceu. Um 500 quase sempre deixa rasto, com um ficheiro e um número de linha.

502: a máquina da frente recebeu uma má resposta

Um 502 vem de um proxy: Nginx, um balanceador, uma CDN. Transmitiu o pedido do seu visitante ao servidor de trás e recebeu de volta algo inutilizável, ou nada de todo.

As três causas habituais:

• O processo de trás está morto ou nunca arrancou: PHP-FPM parado, um serviço Node em falha, um contentor que não voltou depois de um deploy.
• O caminho de comunicação está errado: um socket renomeado, uma porta alterada, um endereço interno que mudou durante uma atualização.
• O processo foi terminado por falta de memória. O registo do sistema di-lo, a aplicação não.

Onde ver: o estado do serviço que está atrás do proxy, antes do código. Um 502 é a única das três respostas que quase nunca nasce do seu próprio programa, e é por isso que tantas vezes é mal atribuída.

503: o servidor recusa, temporariamente

Um 503 é uma resposta deliberada: agora não. Ou o site está em modo manutenção, ou o servidor ficou sem capacidade e recusa em vez de ruir.

É a mais tranquilizadora das três: nada está partido. É também a que dura mais tempo, porque costuma seguir-se a um pico de tráfego ou a uma fila que não se esvazia. E é a única que pode ser a resposta certa: durante uma manutenção anunciada, um 503 acompanhado de um cabeçalho Retry-After é exatamente o que deve ser devolvido.

Onde ver: se ficou ativa uma flag de manutenção, e depois a carga. Um modo manutenção esquecido após um deploy de sexta-feira é um clássico absoluto. Verifique-o antes de supor seja o que for sobre a carga: custa dez segundos e explica boa parte dos 503.

Onde ler o registo, conforme a pilha

tail -n 100 /var/log/nginx/error.log        # Nginx, incluindo 502 e 504
tail -n 100 /var/log/apache2/error.log      # Apache
journalctl -u php8.3-fpm --since "10 min ago"   # PHP-FPM, processos mortos
tail -n 100 storage/logs/laravel.log        # a aplicação, para os 500
df -h && free -m                            # disco cheio, memória esgotada

A ordem importa: o registo do servidor web diz que camada falhou, o registo da aplicação diz porquê. Começar pelo segundo quando a falha é um 502 é procurar um erro num ficheiro que nunca foi executado.

O que verificar no alojamento antes de acusar o seu código

Três coisas, e demoram dois minutos:

• A página de estado do alojamento. Uma manutenção de base de dados partilhada produz 500 em toda a gente ao mesmo tempo.
• As quotas. Número de processos, memória por processo, ligações simultâneas à base: ultrapassá-las produz exatamente os mesmos sintomas de um erro de programação.
• Um débito recusado. Um serviço suspenso por falta de pagamento responde muitas vezes com um 503, e o aviso original foi para o spam há três semanas.

Lembre-se sobretudo de que ninguém o avisará espontaneamente: uma página de estado verde enquanto o seu site devolve 500 é uma situação perfeitamente normal do ponto de vista do alojamento, já que a máquina dele responde.

O que dizer ao cliente entretanto

É o parágrafo que ninguém escreve e que toda a gente procura. Bastam duas linhas, e não mencionam nenhum código:

O site mostra um erro desde as 14:20. Já identificámos de onde vem e estamos a trabalhar nisso. Dou-lhe notícias às 15:00.

Não diga «erro 502», ninguém sabe o que é e dá a impressão de que está a recitar. Não prometa uma hora de reposição enquanto a causa for desconhecida. E avise antes que lho peçam: um cliente que descobre a falha sozinho recorda o incidente, um cliente avisado recorda a resposta.

Os três erros de diagnóstico que custam mais tempo

Reiniciar antes de ler. Um reinício apaga normalmente o rasto do que se partiu: o processo morto volta, o registo recomeça, e a falha regressa duas horas depois sem que saiba mais. Ler primeiro, reiniciar depois, por esta ordem, por mais forte que seja a tentação.

Julgar que o código aponta o culpado. Aponta a camada que comunicou o problema, não a que o causou. Um 502 devolvido pelo Nginx é quase sempre um problema de PHP, e um 500 aplicacional é por vezes um disco cheio, ou seja um problema de sistema.

Tratar um incidente isolado como uma tendência. Um único 502 às três da manhã, durante uma rotação de registos, não exige ação nenhuma. Três 502 no mesmo dia exigem. A diferença só é visível se algo guardar o histórico, e é esse o verdadeiro contributo de uma vigilância face a ler um registo de vez em quando.

O que estes códigos não dizem

Não dizem se o visitante viu a página. Um utilizador cujo navegador a tinha em cache não deu por nada; outro, chegado no mesmo momento a partir de um resultado de pesquisa, viu o erro em ecrã inteiro. Também não dizem quantas pessoas são afetadas: um erro que só atinge uma rota precisa, um formulário de encomenda por exemplo, pode devolver um volume ridículo de 500 e custar caríssimo.

O que os três têm em comum

Nos três casos, a máquina está de pé. Alguma coisa respondeu. Isso já afasta o DNS, a rede e o alojamento, e é precisamente o que torna útil ler este código antes de tudo o resto.

Se nada responder de todo, o problema está noutro lado, e os primeiros quinze minutos passam-se de outra maneira.

Dois vizinhos merecem ser distinguidos, porque são muitas vezes confundidos com esta família. Um 404 não é uma falha: é a resposta correta a um pedido de uma página que não existe, e classifica-se com outras regras. Um aviso de certificado não é sequer um código de erro: o servidor responde perfeitamente, é o navegador que se recusa a mostrar, e essa falha não deixa rasto nos seus registos.

A pergunta que ninguém faz

Seja qual for o código obtido, a pergunta útil vem depois: durante quanto tempo esteve a ser devolvido antes de o saber? Um 500 que dura quatro minutos não é um acontecimento. O mesmo 500 descoberto na manhã seguinte por um cliente é outra história, e a diferença nada tem a ver com o código.

É também a única parte que pode ser quantificada: o que custa realmente uma hora de indisponibilidade depende muito menos da natureza da falha do que do tempo que passou no ecrã.