Erro 502 Bad Gateway: o que é e como corrigir

Algumas tardes, ao abrir um site que uso com frequência, a página não carregou e apareceu a mensagem “502 Bad Gateway”. Primeiro pensei que era um bug temporário: atualizei a página, troquei de navegador e reiniciei o Wi‑Fi. Nada funcionou. Pesquisei o que significa esse erro e descobri que é muito comum e pode afetar qualquer site por diferentes motivos.

Este guia explica em linguagem simples o que é um 502 Bad Gateway, as causas mais comuns, passos práticos para solucionar o problema tanto para usuários quanto para administradores, além de checklists, um fluxo de decisão e dicas avançadas para depuração.

O que é o erro 502 Bad Gateway

Um 502 Bad Gateway normalmente indica um problema de comunicação entre servidores. Em arquiteturas web modernas, uma requisição do seu navegador muitas vezes passa por vários componentes: balanceadores de carga, servidores proxy, servidores de aplicação, caches e serviços terceiros. Se um desses componentes retornar uma resposta inválida, vazia ou com erro para outro servidor que está intermediando a requisição, o cliente (seu navegador) pode receber um 502.

Em termos simples: seu computador pediu dados a um servidor A, que por sua vez precisava conversar com o servidor B. O servidor A não obteve a resposta adequada do servidor B e, por isso, respondeu ao seu navegador com 502 Bad Gateway.

Definição rápida: 502 Bad Gateway — servidor intermediário recebeu uma resposta inválida de outro servidor a montante.

Causas comuns

• Problema temporário no servidor remoto (ex.: serviço em falha ou sobrecarregado).
• Timeout entre servidores devido a lentidão na rede ou em serviços a montante.
• Configuração incorreta em proxy reverso (Nginx, HAProxy) ou balanceador de carga.
• Falha na CDN ou configuração de cache inconsistente.
• Erro em servidores de aplicação (crash, estouro de recursos, exceptions não tratadas).
• DNS desatualizado ou resolución incorreta que aponta para um backend errado.

Importante: na maioria das vezes o erro é do lado do servidor, não do seu dispositivo. Mas existem casos em que a causa está no cliente (por exemplo, cache corrompido ou bloqueios de rede).

Quando não é 502 e o que significam erros similares

• 500 Internal Server Error: erro genérico no próprio servidor que processa a requisição.
• 503 Service Unavailable: servidor indisponível, normalmente por manutenção ou sobrecarga.
• 504 Gateway Timeout: servidor intermediário não recebeu resposta a tempo do servidor upstream.

Contraexemplo útil: se você receber 404, o servidor respondeu corretamente que o recurso não existe — não é um problema de gateway.

O que fazer imediatamente como usuário

1. Atualizar a página 1–2 vezes. Muitas falhas são momentâneas.
2. Abrir o site em outro navegador ou aba anônima. Às vezes extensões interferem.
3. Limpar cache do navegador e cookies (instruções rápidas abaixo).
4. Reiniciar o roteador/modem (em casos raros, falhas de rede local podem corromper pacotes).
5. Tentar outro dispositivo ou outra rede (por exemplo, dados móveis) para eliminar restrições de rede local

Como limpar cache no navegador (passo a passo)

• Abra o histórico do navegador (Ctrl+H em Windows) ou o menu de configurações.
• Escolha Limpar dados de navegação.
• Marque Imagens e arquivos em cache e Cookies se necessário.
• Confirme e recarregue a página.

Flush DNS (Windows)

Se o problema for causado por um registro DNS corrompido localmente, limpe o cache DNS:

ipconfig /flushdns

Depois reinicie o navegador e tente novamente.

Passo a passo profundo para administradores e desenvolvedores

Se você administra o site, o fluxo de investigação é diferente: diagnostique a cadeia completa entre o cliente e os serviços a montante.

1. Verifique a saúde do servidor web e do balanceador de carga.
   • Logs do Nginx/Apache ou do balanceador normalmente mostram a causa (ex.: connection refused, upstream timed out).
2. Cheque logs do aplicativo. Procure por exceções, out-of-memory ou reinícios recentes.
3. Monitoramento de recursos: CPU, memória, file descriptors, uso de threads/processos.
4. Verifique a disponibilidade dos serviços upstream (bancos, APIs de terceiros) com requisições diretas.
5. Revise configurações de proxy e timeouts (Nginx proxy_read_timeout, proxy_connect_timeout).
6. Teste a resolução DNS do servidor e confirme que registros apontam para os backends corretos.
7. Se usar CDN, valide as regras de cache, cabeçalhos e se a CDN está pontuando para o endereço correto.

Exemplo de causa comum em Nginx

Nginx recebe a requisição do cliente e a repassa a um upstream (por example, gunicorn). Se o gunicorn estiver sobrecarregado e não aceitar conexões, Nginx pode devolver 502 com mensagens como “upstream prematurely closed connection” nos logs.

Testes úteis

• cURL direto ao backend para ver se responde: curl -I http://backend:porta/endpoint
• Verificar conexões TCP estabelecidas com netstat/ss.
• Consultar métricas de tempo de resposta e latência entre serviços.

Verificando CDN e cache reverso

CDNs aceleram sites, mas uma configuração incorreta pode provocar 502s para usuários. Pontos a checar:

• O endpoint de origem está correto e acessível pela CDN.
• As regras de cache não estão servindo uma versão inválida com cabeçalhos corrompidos.
• Certificados SSL/TLS entre CDN e origem estão válidos se o tráfego for HTTPS.

Se a CDN estiver em manutenção ou com falha, usuários em certas regiões podem ver 502 enquanto outros não.

Soluções específicas e alternativas

• Aumentar timeouts entre proxy e servidor de aplicação para evitar 504/502 por latência.
• Dimensionar instâncias do serviço (mais réplicas) se estiver sobrecarregado.
• Habilitar circuit breakers e retries com backoff em chamadas a serviços terceiros.
• Utilizar health checks agressivos no balanceador para remover backends erráticos do pool.

Alternativa quando mudanças na infra não são imediatas: habilitar página de manutenção ou fallback local para minimizar impacto ao usuário.

Checklist rápido para diagnosticar 502

Para usuários:

• Atualizar a página.
• Testar outro navegador.
• Limpar cache e cookies.
• Tentar outra rede.

Para administradores:

• Verificar logs do proxy/webserver.
• Validar disponibilidade dos serviços a montante.
• Conferir timeouts e limites de conexões.
• Checar integrações de CDN e DNS.

Fluxo de decisão (Mermaid)

flowchart TD
  A[Usuário vê 502] --> B{O problema é local?}
  B -- Sim --> C[Limpar cache, trocar navegador, testar rede]
  B -- Não --> D{Você administra o site?}
  D -- Não --> E[Aguardar ou contatar suporte do site]
  D -- Sim --> F[Verificar logs do proxy]
  F --> G{Log aponta para upstream?}
  G -- Sim --> H[Verificar serviço a montante: saúde e métricas]
  G -- Não --> I[Revisar configuração de proxy/CDN/DNS]
  H --> J{Serviço a montante está errado?}
  J -- Sim --> K[Reiniciar/scale/patch do serviço]
  J -- Não --> I
  I --> L[Testar após correções]
  L --> M[Fim]

Critérios de aceitação para considerar o problema resolvido

• O site responde com status HTTP 200 para as URLs críticas.
• Logs não mostram 502s repetidos em um intervalo monitorado (ex.: 30 minutos).
• Métricas de latência e erro voltaram aos níveis normais.
• Health checks do balanceador consideram os backends saudáveis.

Boas práticas para evitar 502 recorrentes

• Monitoramento proativo de serviços e alertas por erro 5xx.
• Testes de carga para identificar limites antes que usuários os encontrem.
• Timeouts configuráveis e tolerância a falhas em integrações externas.
• Deploys com estratégia canary/rolling para reduzir impacto de regressões.

Playbook de resposta rápida para incidentes 502

1. Ativar canal de comunicação (chat/phone) com equipe de SRE/desenvolvimento.
2. Recolher primeiras evidências: endpoint afetado, timestamp, regiões afetadas.
3. Consultar dashboards de monitoramento e logs do proxy imediatamente.
4. Isolar backend defeituoso do pool para reduzir impacto.
5. Aplicar rollback se o erro começou após deploy recente.
6. Executar ações corretivas (restart, scale, fix de configuração).
7. Monitorar e validar que os 502 cessaram.
8. Fazer RCA e medidas preventivas.

Perguntas frequentes rápidas

• O 502 pode afetar apenas alguns usuários?
  Sim. Problemas de CDN, roteamento ou regras geográficas podem fazer o erro ser visto apenas por parte dos visitantes.

• Posso evitar 502 reiniciando sempre o servidor?
  Reiniciar pode ser uma correção temporária, mas não resolve a raiz do problema. Use apenas como medida emergencial.

• O erro pode ser causado por DNS?
  Sim. Se o DNS resolver para um IP errado ou desatualizado, clientes podem atingir um backend incorreto.

Resumo e próximos passos

• 502 Bad Gateway é, em geral, um sintoma de falha na comunicação entre servidores.
• Para usuários: tente atualizar, limpar cache, trocar de navegador ou usar outra rede.
• Para administradores: verifique logs, saúde dos serviços a montante, configuração de proxy/CDN e timeouts.
• Tenha um playbook e monitoramento para reduzir tempo médio de reparo (MTTR).

Se ainda estiver inseguro sobre a origem do erro no seu caso específico, cole aqui as mensagens de log relevantes (sem dados sensíveis) ou descreva a arquitetura para que eu possa ajudar a interpretar os sinais.

Glossário rápido

• Gateway: servidor que encaminha requisições entre clientes e serviços.
• Upstream: o serviço a montante ao qual um proxy encaminha a requisição.
• CDN: rede de distribuição de conteúdo que cacheia e entrega recursos.

Obrigado por ler. Se quiser, compartilhe qual navegador/dispositivo você usa e o horário em que viu o erro; posso sugerir testes específicos.

Conclusão

O erro 502 pode ser frustrante, mas frequentemente é temporário ou diagnosticável com os passos corretos. Verifique a cadeia entre cliente e serviços, use logs e métricas, e implemente práticas de resiliência para reduzir ocorrências futuras.