HTTPTools

HTTP 502 Bad Gateway

A reclamação do intermediário: um proxy ou CDN perguntou ao servidor real e recebeu lixo — ou nada — de volta.

O que significa o HTTP 502

HTTP 502 Bad Gateway vem de um intermediário — nginx, um load balancer, Cloudflare — que encaminhou sua requisição a um servidor upstream e recebeu uma resposta inválida: uma conexão recusada, uma falha no meio da resposta, ou bytes que não se analisam como HTTP.

O culpado nomeado quase nunca é o próprio proxy; é o servidor de aplicação atrás dele que está fora do ar, sobrecarregado ou inacessível.

Causas comuns de erros 502

  • O servidor de aplicação (PHP-FPM, Node, gunicorn, etc.) travou ou não está em execução.
  • O proxy aponta para a porta/socket errado, ou um firewall bloqueia a conexão upstream.
  • A resposta upstream excedeu os buffers ou atingiu o timeout no meio da transferência.
  • Um deploy reiniciou os backends enquanto o tráfego estava fluindo.
  • Com CDNs como Cloudflare: o servidor de origem está fora do ar enquanto a edge está bem.

Como corrigir como visitante

  • Recarregue após um minuto — 502s durante deploys se resolvem sozinhos.
  • Verifique a página de status do serviço se isso continuar acontecendo.

Como corrigir como desenvolvedor

  • Verifique se o processo upstream está vivo e escutando no endereço que o proxy espera.
  • Leia o log de erros do proxy — o nginx informa exatamente por quê (connect() failed, upstream prematurely closed, etc.).
  • Verifique portas, caminhos de socket unix e regras de firewall entre proxy e aplicação.
  • Adicione health checks para que o load balancer pare de rotear para instâncias mortas.

Exemplo de resposta

HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html

<html><body><h1>502 Bad Gateway</h1></body></html>

Perguntas frequentes

Qual é a diferença entre 502 e 504?

502 significa que o upstream respondeu com algo inválido (ou recusou a conexão); 504 significa que ele simplesmente não respondeu dentro do tempo limite.

Por que o Cloudflare mostra 502?

A edge do Cloudflare não conseguiu obter uma resposta válida do seu servidor de origem — a origem está fora do ar, inacessível ou retornando respostas malformadas.

Um 502 é temporário?

Geralmente sim — deploys e reinícios causam 502s breves. 502s persistentes significam que o backend está genuinamente fora do ar ou mal configurado.