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 deu uma resposta ruim (ou desligou), 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 não têm para onde ir.

• 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.

• Um firewall ou uma mudança de rede entre o proxy e a origem. Por exemplo, uma CDN não consegue mais alcançar uma origem cujo endereço IP ou regras de firewall mudaram.

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 Cabeçalhos HTTP do DNS Robot solicita a página a partir dos nossos servidores e mostra o código de status exato. Se nós também recebermos um 502, o problema é do site, não seu. Um Teste de Ping mostra se a máquina do servidor responde de alguma forma.

• Force o recarregamento e limpe o cache. Ctrl + Shift + R (Mac: Cmd + Shift + R) ignora a cópia em cache, caso uma página de erro antiga 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 quase sempre registra exatamente o que deu errado. Siga estas quatro verificações em ordem.

1. Leia o log de erros do proxy

Reproduza o 502 e leia as últimas linhas do log de erros no servidor proxy:

# 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

Estas mensagens do nginx cobrem a grande maioria dos 502, e cada uma aponta para a correção:

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?
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?
grep -rn "proxy_pass\|fastcgi_pass" /etc/nginx/sites-enabled/

# 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). Depois de qualquer mudança, rode sudo nginx -t e sudo systemctl reload nginx.

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:

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;
}

Depois do nginx -t e de um reload, a página retornou 200. A lição: se só algumas páginas retornam 502 enquanto o resto do site funciona, procure um limite de tamanho, como cabeçalhos ou cookies grandes 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 (server.keepAliveTimeout, no Node.js 26 e anteriores), 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 // keep slightly above keepAliveTimeout

502 Bad Gateway na Cloudflare

Atrás da Cloudflare, veja primeiro quem gerou a página de erro:

• Página com a marca da Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): a Cloudflare está funcionando, mas não conseguiu obter uma resposta válida do seu servidor de origem. Verifique se a origem está no ar, escutando nas portas 443/80, e se o firewall dela não está bloqueando as faixas de IP da Cloudflare. Teste a origem diretamente com o Verificador de Portas.

• Página de 502 simples, sem marca: se ela não menciona a cloudflare (por exemplo, mostra nginx ou Apache), o 502 foi gerado pelo seu próprio servidor de origem. Use os passos do lado do servidor acima. Uma página em branco com apenas "cloudflare" no rodapé vem da própria Cloudflare, por exemplo durante um breve redirecionamento de tráfego ou quando a origem envia conteúdo gzip corrompido.

• O IP da origem mudou? Se você trocou de hospedagem, atualize o registro A no DNS da Cloudflare. Um DNS Lookup mostra o que o mundo vê no momento.

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.