Erro 502 Bad Gateway: o que é e como resolver

O que é o erro 502 Bad Gateway?

502 Bad Gateway é um código de status HTTP que significa que o servidor que está respondendo a você atua como gateway ou proxy e recebeu uma resposta inválida do servidor por trás dele. O padrão HTTP (RFC 9110, seção 15.6.3) o define exatamente assim: o servidor, "enquanto atuava como gateway ou proxy, recebeu uma resposta inválida de um servidor de entrada que acessou ao tentar atender à requisição".

A maioria dos sites modernos tem pelo menos duas camadas. Um servidor na frente, como nginx, Apache, Cloudflare ou um balanceador de carga na nuvem, aceita a sua conexão e repassa a requisição para uma aplicação upstream, como PHP-FPM, um app Node.js, o Gunicorn do Python ou um container. Quando esse upstream está fora do ar, trava ou responde algo que o proxy não consegue usar, o proxy não tem nada para entregar a você e retorna 502.

O ponto importante é que o próprio gateway está funcionando. Ele recebeu a sua requisição e respondeu. A falha está um passo mais atrás.

As várias caras do erro 502

O código de status é o mesmo em todo lugar, mas a página que você vê depende de qual proxy a gerou:

Seja qual for a versão que você vê, o nome do proxy no rodapé é uma pista útil: ele diz ao dono do site qual camada investigar.

502 vs. 500 vs. 503 vs. 504: qual é a diferença?

Todos os códigos 5xx significam "problema no servidor", mas cada um aponta para uma camada diferente:

Uma regra rápida: 502 = o upstream recusou a conexão, desligou ou deu uma resposta ruim, 504 = o upstream não respondeu a tempo. Os nossos guias sobre os vizinhos explicam cada um em detalhe: 500 Internal Server Error, 503 Service Unavailable e 504 Gateway Timeout.

O que causa o erro 502 Bad Gateway?

• A aplicação upstream não está rodando. O PHP-FPM, o Node, o Gunicorn ou o container travou, não iniciou depois de um deploy ou está reiniciando.
• O proxy aponta para o lugar errado. O proxy_pass ou o fastcgi_pass usa a porta errada, um caminho de socket do PHP antigo depois de uma atualização, ou localhost dentro de um container Docker.
• A aplicação trava em algumas requisições. Uma página dispara um encerramento por falta de memória ou uma exceção não tratada, e a conexão fecha antes da resposta.
• Todos os workers estão ocupados. O PHP-FPM atingiu o pm.max_children, então as novas requisições esperam na fila do socket. A maioria acaba em 504 por timeout; quando a fila enche, o nginx registra (11: Resource temporarily unavailable) e retorna 502.
• Os cabeçalhos da resposta são grandes demais. Cookies grandes ou cabeçalhos de segurança extensos estouram o proxy_buffer_size do nginx.
• Incompatibilidade de keep-alive atrás de um balanceador de carga. A aplicação fecha conexões ociosas antes do que o balanceador espera, então o balanceador envia uma requisição para uma conexão que está sendo fechada.
• O proxy não alcança o upstream depois de uma mudança de rede. Um firewall que rejeita o proxy, ou um upstream que mudou para outro IP, gera 502 (Connection refused, No route to host). Um firewall que descarta pacotes em silêncio gera 504, e atrás da Cloudflare isso aparece como 521 ou 522.

Como resolver o erro 502 como visitante

Você não consegue consertar o servidor de outra pessoa, mas estes passos confirmam que o problema está mesmo do lado deles e eliminam as raras causas locais:

• Espere de 30 a 60 segundos e recarregue (Ctrl + R, ou Cmd + R no Mac). Muitos 502 duram só o tempo de um deploy ou de um reinício.
• Verifique se está fora do ar para todos. O Verificador de site fora do ar do DNS Robot abre a página a partir de 11 lugares, e o Verificador de Cabeçalhos HTTP mostra o código de status exato que o nosso servidor recebe. Se eles também veem um 502, o problema é do site, não seu.
• Force o recarregamento com Ctrl + Shift + R (Mac: Cmd + Shift + R), caso uma página de erro em cache esteja sendo mostrada a você.
• Limpe o cache de DNS se o site mudou de hospedagem recentemente, para chegar ao servidor novo. Veja como limpar o DNS em todos os sistemas.
• Desligue VPNs e proxies. O seu próprio proxy pode ser o "gateway" que falha, principalmente em redes de trabalho.
• Teste outro navegador ou o celular com dados móveis. Se funcionar ali, limpe os cookies desse site.

Como resolver o 502 Bad Gateway no seu servidor

Do lado do servidor, o 502 é um dos erros mais fáceis de resolver, porque o proxy geralmente registra o que deu errado (as exceções são a condição de corrida de keep-alive de um balanceador e os 502 da própria Cloudflare). Siga estas três verificações em ordem; a quarta parte é um exemplo real.

1. Leia o log de erros do proxy

Reproduza o 502 e leia as últimas 50 linhas do log de erros do proxy (os comandos estão abaixo da tabela). Cada uma destas mensagens do nginx aponta para a sua própria correção:

# nginx
sudo tail -n 50 /var/log/nginx/error.log

# Apache
sudo tail -n 50 /var/log/apache2/error.log    # Debian/Ubuntu
sudo tail -n 50 /var/log/httpd/error_log      # RHEL/Alma/Rocky

2. Verifique se a aplicação upstream está rodando

# PHP-FPM (adjust the version)
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

# Node.js under PM2
pm2 status
pm2 logs --lines 50

# Docker
docker ps -a          # look for containers that keep restarting
docker logs --tail 50 <container>

# Was it killed for using too much memory?
sudo dmesg -T | grep -i "killed process"

Se o serviço estiver parado, inicie-o e descubra por que ele parou: um deploy que falhou, um erro de sintaxe na nova versão ou o OOM killer (que encerra processos por falta de memória). No log do PHP-FPM, server reached pm.max_children setting significa que todos os workers estavam ocupados. Aumente o pm.max_children só se o servidor tiver RAM para isso; caso contrário, encontre as requisições lentas que prendem os workers.

3. Confirme que o proxy_pass aponta para a porta ou o socket certo

Compare aquilo com que o nginx foi configurado para falar com o que está realmente escutando:

# What is nginx proxying to?
sudo nginx -T 2>/dev/null | grep -n "proxy_pass\|fastcgi_pass"

# What is actually listening?
sudo ss -tlnp            # TCP ports and their processes
ls -l /run/php/          # PHP-FPM socket files

Dois descompassos clássicos: depois de atualizar o PHP, o socket passa a ser php8.3-fpm.sock enquanto o nginx ainda aponta para php8.1-fpm.sock; e, dentro do Docker, proxy_pass http://localhost:3000 aponta para o próprio container do nginx, e não para a aplicação, então use o nome do serviço do Compose (http://app:3000).

4. Um exemplo real: como o dnsrobot.net serviu um 502

Isso aconteceu conosco em 30 de setembro de 2026. Depois de publicarmos um lote de novos posts no blog, exatamente um deles retornou 502 Bad Gateway pelo nginx 1.24, enquanto todas as outras páginas funcionavam. O app Next.js por trás do nginx retornava essa mesma página com 200 OK quando a solicitávamos diretamente na porta 3000. Ou seja, a aplicação estava bem e o gateway é que estava falhando.

O log de erros do nginx tinha a resposta em uma linha: upstream sent too big header while reading response header from upstream. Os cabeçalhos de resposta daquela página somavam 4.087 bytes, a maior parte de um longo cabeçalho Content-Security-Policy mais cabeçalhos Link de preload. O nginx lê a primeira parte da resposta, incluindo todos os cabeçalhos, em um buffer definido por proxy_buffer_size, que por padrão tem o tamanho de uma página de memória: 4 KB no nosso servidor. Isso deixava só 9 bytes de folga, e o bloco completo de cabeçalhos, incluindo a linha de status, estourou o buffer.

A correção foram três linhas no bloco location que faz o proxy para a aplicação; depois do nginx -t e de um reload, a página retornou 200:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;        # room for large headers (was the 4k default)
    proxy_buffers 4 32k;
    proxy_busy_buffers_size 64k;
}

A lição: se só algumas páginas retornam 502 enquanto o resto do site funciona, procure um limite de tamanho, como cabeçalhos grandes ou valores de Set-Cookie nessas páginas, antes de suspeitar da aplicação.

Node.js atrás de um balanceador de carga: 502 aleatórios

Se você roda Node.js atrás de um AWS Application Load Balancer ou de um balanceador parecido e vê 502 ocasionais sem nenhum erro nos logs da aplicação, verifique os timeouts de keep-alive. O servidor HTTP do Node fecha conexões keep-alive ociosas depois de 5 segundos por padrão no Node 26 e anteriores (server.keepAliveTimeout; o Node 24.6 e o 22.19 acrescentaram um keepAliveTimeoutBuffer de 1 segundo, e a próxima versão major eleva o padrão para 65 segundos), enquanto um AWS ALB mantém conexões ociosas abertas por 60 segundos. Às vezes o balanceador reutiliza uma conexão no exato momento em que o Node a fecha, e essa requisição volta como 502.

A correção é manter o timeout da aplicação maior que o do balanceador:

const server = app.listen(3000)
// Must be longer than the load balancer's idle timeout (ALB default: 60s)
server.keepAliveTimeout = 65_000
server.headersTimeout = 66_000 // só é necessário antes do Node 18; não atrapalha depois

502 Bad Gateway na Cloudflare

Atrás da Cloudflare, veja primeiro quem gerou a página de erro (guia da Cloudflare sobre 502/504):

• Página com a marca da Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): o seu próprio servidor de origem retornou um 502 ou 504 para a Cloudflare. Resolva na origem com os passos do lado do servidor acima. Se a Cloudflare não consegue se conectar à origem de jeito nenhum, você recebe 521 ou 522, não 502.
• Uma página simples com "502 Bad Gateway" e "cloudflare" embaixo: esta vem da própria Cloudflare. A documentação dela cita duas causas: a origem enviando conteúdo gzip corrompido, ou conteúdo gzip sem um Content-Length atualizado (desligue a compressão na origem para testar), e um pico repentino de tráfego em um data center da Cloudflare, que passa sozinho.
• Uma página que cita nginx ou Apache: em geral a requisição chegou ao seu servidor sem passar pela Cloudflare, então o registro DNS não está com proxy (nuvem cinza, "DNS only") ou você está olhando a origem diretamente (a menos que uma Cache Rule ative "Origin error page pass-through").
• Mudou de hospedagem? Atualize o registro A da origem no DNS da Cloudflare (um IP de origem errado costuma aparecer como 521, 522 ou 523). Um DNS Lookup só mostra a origem de registros com nuvem cinza (DNS only); registros com proxy respondem com os IPs da própria Cloudflare.

O erro 502 prejudica o SEO?

Uma queda curta, não. A documentação do Google diz que erros de servidor 5xx fazem os rastreadores reduzirem temporariamente o ritmo de rastreamento. Páginas já indexadas continuam no índice no início, mas, se os erros persistirem, o Google acaba removendo esses URLs.

Então um 502 que dura alguns minutos durante um deploy é inofensivo. Um 502 em páginas importantes que dura dias, ou que aparece de forma intermitente por semanas, pode reduzir o rastreamento e custar posições. Monitore os seus URLs principais e confira o relatório Estatísticas de rastreamento no Search Console depois de qualquer queda.