Códigos de status 5xx explicados: quando o seu servidor é o problema
Um código de status 5xx significa que a sua infraestrutura falhou, não a requisição do visitante. O servidor aceitou a requisição, entendeu ela, e depois não conseguiu produzir uma resposta válida, então todo 5xx no seu site é um incidente do qual você é dono.
O que separa 5xx de 4xx
A RFC 9110 define 5xx como "Erro de Servidor": o servidor está ciente de que errou ou é incapaz de executar o método solicitado. Essa é a distinção inteira. Um 404 diz "não há nada aqui". Um 500 diz "há algo aqui e eu quebrei enquanto o produzia".
Duas consequências seguem disso. Primeiro, um 5xx geralmente pode ser tentado de novo, porque a mesma requisição bem pode ter sucesso um segundo depois assim que o componente que está falhando se recupera. Segundo, os buscadores tratam um 5xx como um sinal temporário e desaceleram o rastreamento em vez de desindexar imediatamente, embora um 5xx persistente ao longo de dias eventualmente custe páginas indexadas.
Qual salto falhou
Leia um código 5xx como um mapa de onde a requisição morreu. Quase todo site moderno coloca pelo menos um proxy na frente da aplicação, então o código diz de qual lado dessa fronteira veio a falha.
| Código | Quem o produziu | O que aconteceu |
|---|---|---|
| 500 Internal Server Error | A própria aplicação | Exceção não tratada ou condição inesperada dentro da aplicação |
| 501 Not Implemented | O servidor | O método da requisição não é suportado de forma alguma |
| 502 Bad Gateway | O proxy, CDN ou balanceador de carga | O backend respondeu, mas com algo inválido, ou fechou a conexão |
| 503 Service Unavailable | O servidor ou proxy, deliberadamente | Sobrecarregado ou em manutenção, e recusando trabalho de propósito |
| 504 Gateway Timeout | O proxy, CDN ou balanceador de carga | O backend nunca respondeu a tempo |
| 505 HTTP Version Not Supported | O servidor | A versão do protocolo na requisição não é suportada |
502, 503 e 504 carregam o maior valor diagnóstico, porque cada um nomeia uma falha diferente do mesmo backend: resposta inválida, resposta recusada, nenhuma resposta. O guia do 502 Bad Gateway cobre o primeiro deles em profundidade, incluindo as linhas de log do proxy que identificam a falha exata.
Causas comuns por trás de respostas 5xx
- Travamentos de aplicação. Uma exceção não tratada, uma conexão de banco de dados falhada ou um valor nulo em um lugar inesperado produz 500 em qualquer rota que toca o caminho de código quebrado.
- Processo de backend não rodando. Um servidor de aplicação parado, um pool de PHP-FPM morto ou um contêiner que falhou na verificação de saúde não dá nada para o proxy conversar, o que aparece como 502.
- Esgotamento de recursos. Sem memória, sem descritores de arquivo, sem threads de worker ou sem conexões de banco de dados. Geralmente começa como erros intermitentes sob carga antes de ficar constante.
- Dependências lentas. Uma consulta lenta, uma API de terceiro lenta ou um cold start empurra o tempo de resposta além do timeout do proxy e vira 504.
- Implantações e reinicializações. Qualquer janela onde o processo antigo parou e o novo ainda não começou a servir produz uma rajada de 502 ou 503.
- Erros de configuração. Um endereço de upstream errado, uma configuração TLS ruim entre proxy e backend, ou uma incompatibilidade de protocolo como falar HTTP com uma porta HTTPS.
- Disco cheio. Uma causa subestimada. Logs ou arquivos temporários enchem o volume, sessões ou caches param de escrever, e a aplicação começa a falhar de formas que parecem aleatórias.
Como trabalhar em um 5xx
- Confirme o código e a origem dele. Busque os cabeçalhos diretamente e veja qual componente assinou a resposta:
Um cabeçalhocurl -sS -o /dev/null -D - https://example.com/Server:ou de CDN no erro diz se a borda ou a origem o gerou. - Teste a origem diretamente, contornando o proxy. Se o backend responde 200 na própria porta dele enquanto a URL pública responde 502, a falha está na camada do proxy ou na ligação entre os dois.
- Leia o log de erro do proxy em seguida, não o log da aplicação. Proxies reversos nomeiam a falha com precisão, por exemplo
connect() failed (111: Connection refused)ouupstream timed out, o que separa imediatamente "backend fora do ar" de "backend lento". - Depois leia o log da aplicação. Para um 500, o stack trace é a resposta. Para 502 e 504, a aplicação muitas vezes não registra nada, e essa ausência já é informativa.
- Verifique os recursos no host. Memória, disco, contagens de conexão e saturação de worker. 5xx intermitente sob tráfego é quase sempre um limite sendo atingido.
- Olhe o que mudou. Implantações, envios de configuração, renovações de certificado e atualizações de dependência respondem por uma grande parte dos surtos repentinos de 5xx.
Pegando erros 5xx intermitentes
Erros 5xx costumam ser intermitentes, o que é o que torna difícil pegá-los manualmente: a página que você recarrega funciona, e a que o seu cliente carregou não funcionou. Uma verificação HTTP agendada roda continuamente e amostra o site muito mais frequentemente do que você consegue, então uma sequência de erros se torna visível como um padrão em vez de reclamações espalhadas. Verificar a partir de várias localidades também separa uma falha real de servidor de um problema de roteamento ou borda que afeta só parte do mundo, e é por isso que o monitoramento de disponibilidade distribuído usa pontos de verificação espalhados por regiões em vez de um único ponto de observação. Se o código que está falhando é 403, 404 ou 429 em vez disso, a requisição nunca alcançou um backend quebrado, e o guia da família 4xx é o ponto de partida certo.