05 - 5xx - Erro do Servidor (500, 503, 505)

A família de códigos 5xx (Erro do Servidor) indica que o servidor falhou ao processar uma requisição aparentemente válida. Padronizada na RFC 7231 (atualizada pela RFC 9110), essa categoria sinaliza problemas internos do servidor ou de infraestrutura: exceções não tratadas, dependências indisponíveis, timeouts em gateways ou versões HTTP não suportadas. Ao contrário dos códigos 4xx (onde o cliente deve corrigir a requisição), nos 5xx o problema está no lado do servidor — o cliente geralmente só pode tentar novamente mais tarde.

1. Visão Geral da Família 5xx

Os códigos 5xx cobrem falhas desde erros de aplicação até indisponibilidade de infraestrutura. O diagnóstico correto de cada código é fundamental para o trabalho de SREs (Site Reliability Engineers) e administradores de sistemas.

2. 500 Internal Server Error — Erro Genérico de Aplicação

O 500 Internal Server Error é o código mais genérico e temido da família 5xx. Indica que ocorreu uma condição inesperada no servidor que o impediu de atender à requisição. É o "catch-all" para exceções não tratadas, erros de banco de dados, falhas de configuração e bugs no código da aplicação.

Causas Comuns

• Exceções não tratadas no código (NullPointer, IndexError).
• Erro de conexão com o banco de dados (timeout, credenciais inválidas).
• Configuração incorreta do PHP-FPM, Gunicorn, uWSGI.
• Permissões de arquivo inadequadas no servidor web.
• Erro de sintaxe em arquivo .htaccess ou nginx.conf.

HTTP/1.1 500 Internal Server Error
Content-Type: text/html

<html><body><h1>Internal Server Error</h1>
<p>The server encountered an unexpected condition.</p></body></html>

Boas Práticas

• Nunca exponha stack traces em produção (vazam informações sensíveis).
• Registre o erro completo em logs internos com ID de correlação.
• Retorne uma mensagem genérica amigável ao usuário final.

3. 501 Not Implemented — Método Não Suportado

O 501 Not Implemented indica que o servidor não possui a funcionalidade necessária para atender à requisição. É retornado quando o servidor não reconhece o método HTTP utilizado (ex: servidor que não suporta PATCH ou CONNECT). Diferente do 405 (método conhecido mas não permitido para aquele recurso), o 501 significa que o servidor sequer implementa o método.

4. 502 Bad Gateway — Resposta Inválida do Upstream

O 502 Bad Gateway ocorre quando um servidor atua como gateway ou proxy e recebe uma resposta inválida do servidor upstream. É comum em arquiteturas com NGINX na frente de aplicações (Node.js, Python, PHP-FPM), quando o backend falha ou retorna algo inesperado.

Causas Típicas

• Processo backend (Gunicorn, PHP-FPM) travado ou reiniciando.
• Backend retornou resposta malformada (headers inválidos, conexão fechada abruptamente).
• Problema de comunicação entre proxy e upstream (socket fechado).

# Verificando o status do PHP-FPM (comum em 502 no NGINX)
sudo systemctl status php8.1-fpm

# Reiniciando o backend
sudo systemctl restart php8.1-fpm nginx

5. 503 Service Unavailable — Servidor Indisponível

O 503 Service Unavailable indica que o servidor está temporariamente incapaz de atender à requisição, geralmente por sobrecarga ou manutenção programada. É o código correto para indicar indisponibilidade temporária e deve sempre acompanhar o cabeçalho Retry-After.

Cenários Típicos

• Servidor em manutenção programada (deploy, migração).
• Picos de tráfego que excedem a capacidade (Black Friday).
• Limites de conexões atingidos no pool do banco de dados.
• Auto Scaling ainda provisionando novas instâncias.

HTTP/1.1 503 Service Unavailable
Retry-After: 120

{"erro": "Sistema em manutenção. Tente novamente em 2 minutos."}

Importância para SEO

Retornar 503 (e não 500) durante manutenções evita que o Googlebot desindexe o site. O 503 é interpretado como "tente depois", preservando o ranking.

6. 504 Gateway Timeout — Upstream Não Respondeu

O 504 Gateway Timeout indica que um servidor atuando como gateway não recebeu resposta do upstream dentro do tempo limite. É diferente do 502: no 502 o upstream respondeu algo inválido; no 504, o upstream simplesmente não respondeu.

Diagnóstico Comum

• Backend travado em consulta SQL lenta (ex: 30s em banco de 1M de linhas sem índice).
• Dependência externa indisponível (API de pagamento, serviço de email).
• Timeout do NGINX (proxy_read_timeout 60s) atingido.

# Aumentando o timeout do NGINX para backends lentos
# nginx.conf
location /api/ {
    proxy_read_timeout 120s;
    proxy_connect_timeout 10s;
}

# Verificando conexões bloqueadas no backend
ss -tn state established 'sport = :8080' | wc -l

7. 505 HTTP Version Not Supported — Versão Não Suportada

O 505 HTTP Version Not Supported é retornado quando o servidor não suporta a versão do protocolo HTTP utilizada na requisição. Embora raro hoje em dia, pode ocorrer em servidores antigos que só suportam HTTP/1.0 recebendo requisições HTTP/2 ou HTTP/3, ou em servidores modernos recebendo requisições com versões experimentais.

8. Diagnóstico e Troubleshooting de Erros 5xx

Para um administrador de redes, a rápida identificação da origem do erro 5xx é crítica:

# Filtrando erros 5xx no log de acesso do NGINX
awk '$9 ~ /^5/ {print $9, $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn

# Verificando logs de erro do backend (ex: aplicação Node.js)
journalctl -u nodeapp -n 100 --no-pager

# Monitorando saúde do banco de dados durante 500/504
mysql -e "SHOW PROCESSLIST;" | awk '{print $1, $3, $6, $7}'

# Verificando uso de recursos (CPU/RAM/Disk) durante 503
vmstat 1 5 && df -h && free -m

Estratégias de Mitigação

• Circuit Breaker: Interrompe chamadas para serviços falhando repetidamente (evita cascatas de 5xx).
• Retry com Backoff: Cliente tenta novamente após tempo exponencial (para 503 e 504).
• Health Checks: Load balancers marcam instâncias como "doentes" após N erros 500 consecutivos.
• Graceful Degradation: Aplicação retorna dados em cache quando dependência falha.

9. Impacto em Cyber Security

Erros 5xx são vetores importantes em segurança:

• Vazamento de Stack Traces: Expor mensagens de erro detalhadas revela versões de bibliotecas, caminhos de arquivos e estrutura interna — facilita ataques.
• Ataques DoS Induzidos: Atacantes podem disparar consultas custosas para forçar 503/504 e derrubar a aplicação.
• Erro 500 em Auth: Pode revelar se usuário existe ou não (timing attack), mesmo sem exibir mensagem explícita.

10. Conclusão: Quando o Servidor Falha

Os códigos 5xx representam a "pior hora" de uma aplicação web — o momento em que o servidor falha perante o cliente. O diagnóstico correto diferencia um 500 (bug na aplicação) de um 502 (backend morto) ou 504 (timeout de rede), e cada um exige ação diferente da equipe de operações. Para SREs e administradores, a meta é sempre reduzir a taxa de 5xx para zero (ou próximo disso) através de monitoramento pró-ativo, testes de carga, circuit breakers e boa higiene de código. A diferença entre uma aplicação robusta e uma frágil mede-se, muitas vezes, em quantos 5xx seus usuários veem por dia.