Erro 502 Bad Gateway: o que significa e como o resolver
O erro 502 Bad Gateway indica uma resposta inválida do servidor por trás do proxy. Guia para visitantes e administradores: nginx, PHP-FPM, Cloudflare.
O erro 502 Bad Gateway significa que um servidor que atua como gateway ou proxy recebeu uma resposta inválida do servidor por trás dele. O erro surge entre dois servidores, por isso não vem do browser nem do dispositivo do visitante. [1] [2]
Este guia tem duas partes. Se for um visitante, a secção curta mais abaixo indica o que pode tentar. Se gerir o site, a secção de resolução mostra como descobrir que salto devolveu o 502 e como ler a linha de registo que indica a causa, e explica passo a passo a correção e a forma de evitar que o erro se repita.
O que significa o erro 502 Bad Gateway?
Um pedido a um site passa muitas vezes por vários saltos:
browser → CDN or proxy → web server → application
Cada salto reencaminha o pedido para o seguinte. Se o salto que está por trás de um proxy devolver uma resposta que o proxy não consegue usar, o proxy devolve 502. O código de estado não diz qual dos saltos falhou. No nginx, também aparece um 502 quando o upstream recusa a ligação, a interrompe com um reset ou a fecha antes do tempo, por isso o código só lhe diz que o elo por trás do proxy se partiu.
Há duas coisas que um 502 não é. Não é sinal de que o visitante enviou um pedido incorreto. Também não é um timeout (tempo de espera esgotado): um upstream lento dá outro código, explicado na secção seguinte.
502 vs 503 vs 504
Três códigos abrangem a maioria das falhas do lado do servidor entre saltos. Apontam para causas diferentes, por isso leia o código antes de começar a investigar.
| Código | O que aconteceu | Causa típica | O que verificar primeiro |
|---|---|---|---|
| 502 Bad Gateway | O gateway recebeu uma resposta inválida do servidor upstream [1] [2] | A aplicação está em baixo ou recusou a ligação, terminou inesperadamente a meio do pedido ou enviou cabeçalhos que o nginx não consegue aceitar | A linha do registo de erros do nginx correspondente ao pedido |
| 503 Service Unavailable | Temporariamente, o servidor não consegue tratar o pedido [1] | Sobrecarga ou manutenção planeada | A carga do servidor e se há trabalhos em curso |
| 504 Gateway Timeout | O gateway não recebeu a tempo uma resposta do servidor upstream [1] [3] | O upstream é demasiado lento, por exemplo por causa de uma consulta demorada à base de dados, e o timeout do proxy expirou [4] | Que pedido está lento e o que a aplicação está a fazer enquanto espera |
Um 504 é um problema de tempo de resposta: o upstream respondeu tarde demais, e não de forma errada. No nginx, os timeouts de leitura predefinidos do proxy e do FastCGI são de 60 segundos [4] [5].
Aumentar o timeout não resolve um 502
Timeouts como o proxy_read_timeout e o fastcgi_read_timeout só controlam quanto tempo o nginx espera por uma resposta. Um 502 significa que a resposta veio danificada, ficou em falta ou nunca chegou. Aumentar o timeout não muda isso. Só mexa nos timeouts quando o erro for um 504.
Se encontrar um 502 como visitante
Não pode corrigir o servidor, mas pode confirmar que o problema não está do seu lado e comunicá-lo.
- Espere um minuto e recarregue a página. Um reinício ou a publicação de uma nova versão no servidor podem resolver o erro sem que tenha de fazer nada.
- Experimente outro browser ou outra rede, como os dados móveis. Se aí o site carregar, o problema está na sua ligação.
- Consulte a página de estado do site, se existir.
- Anote a hora e o endereço exato que abriu. O responsável pelo site precisa destes dados para encontrar a linha de registo correspondente.
Normalmente, a correção é feita no servidor, por isso só o responsável pelo site pode eliminar o erro. Se o site for seu, siga os passos abaixo.
Como resolver o erro 502 Bad Gateway no seu servidor
Trabalhe de fora para dentro. Em cada passo, exclui um salto antes de passar ao seguinte.
1. Descubra que servidor devolveu o 502
Faça dois pedidos à página. O primeiro usa o caminho público. O segundo liga-se diretamente ao endereço IP do seu servidor de origem e envia o nome do site no cabeçalho Host. Substitua o endereço de exemplo pelo seu.
curl -I "https://www.example.com/"
curl -I --resolve www.example.com:443:203.0.113.10 "https://www.example.com/"Leia a linha de estado e os cabeçalhos de cada resposta:
- Os cabeçalhos
cf-rayeserver: cloudflareindicam que a resposta passou pela Cloudflare. Aparecem mesmo quando o 502 veio da sua origem, por isso não lhe dizem que lado falhou; quem o diz é a própria página (veja a secção sobre a Cloudflare, mais abaixo). - Um cabeçalho
server: nginxno pedido direto significa que foi o nginx da sua origem que gerou o 502.
Se o pedido direto também devolver 502, o problema está na origem: passe ao passo 2. Se o pedido direto devolver 200 e o pedido público devolver 502, a falha está no percurso antes da origem. Analise a própria página de erro, como se explica na secção sobre a Cloudflare, mais abaixo, e veja o passo 7.
2. Leia o registo de erros
Quando o nginx não consegue obter uma resposta utilizável do upstream, escreve o motivo no registo de erros. Leia as linhas mais recentes:
sudo tail -n 50 /var/log/nginx/error.logAssocie a mensagem à causa:
| Linha de registo (contém) | Causa habitual | O que fazer |
|---|---|---|
connect() failed (111: Connection refused) while connecting to upstream |
A aplicação não está em execução ou está à escuta noutra porta | Inicie a aplicação ou corrija a porta (passo 3) |
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) |
O caminho do socket está errado ou o PHP-FPM está parado | Verifique o caminho do socket e o serviço (passos 3 e 4) |
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) |
O proprietário ou as permissões do socket não deixam o nginx ligar-se | Verifique as definições listen.owner, listen.group e listen.mode no pool do PHP-FPM |
upstream prematurely closed connection while reading response header from upstream |
A aplicação foi abaixo ou foi terminada à força durante o pedido, muitas vezes por falta de memória | Verifique a memória e os registos de falhas (passo 5) |
upstream sent too big header while reading response header from upstream |
Os cabeçalhos da resposta são maiores do que o buffer do nginx | Aumente o tamanho do buffer (passo 6) |
no live upstreams while connecting to upstream |
Todos os servidores do bloco upstream estão marcados como em falha | Verifique os servidores do bloco e, depois, a aplicação por trás de cada um (passo 3) |
A linha indica o endereço ou o socket do upstream. Compare-o com aquele em que a aplicação está realmente à escuta.
3. Verifique se a aplicação está em execução
Verifique o serviço e a porta ou o socket em que está à escuta. Use o separador que corresponde à sua stack.
sudo systemctl status php8.3-fpm
sudo ss -lxp | grep phppm2 status
sudo ss -ltnp | grep 3000sudo systemctl status gunicorn
sudo ss -ltnp | grep 8000Se o Node for gerido pelo systemd, use systemctl status <service> em vez de pm2 status. Se o serviço estiver parado, leia os registos antes de o reiniciar, para não perder o motivo da falha. Por exemplo: sudo journalctl -u php8.3-fpm -n 100.
4. Verifique se o proxy_pass ou o fastcgi_pass corresponde à aplicação
O endereço configurado no nginx tem de corresponder à porta ou ao socket do passo 3. Se não corresponder, surgem as linhas «Connection refused» ou «No such file or directory» do passo 2.
Num proxy inverso para uma aplicação numa porta local:
location / {
proxy_pass http://127.0.0.1:3000;
}No PHP-FPM através de um socket Unix:
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}Teste a configuração e, depois, recarregue o nginx. Se o teste falhar, o recarregamento não é executado, por isso o nginx mantém a configuração que já está a funcionar.
sudo nginx -t && sudo systemctl reload nginx5. Verifique a memória e as falhas
A linha upstream prematurely closed connection aponta para um processo que morreu a meio do pedido. Num VPS pequeno, a causa habitual é o OOM killer do kernel, que termina processos quando a memória se esgota. Procure no registo do kernel:
sudo dmesg -T | grep -i -E "out of memory|killed process"
free -hNo PHP-FPM, procure no respetivo registo de erros a mensagem server reached pm.max_children setting. Esta mensagem significa que todos os processos filho (workers) estão ocupados. Cada worker usa RAM, por isso só aumente o pm.max_children depois de confirmar que o servidor tem memória livre para os workers adicionais [6].
Se a memória for simplesmente insuficiente para o site, a solução é um plano maior, e não um timeout mais longo. O artigo sobre estrangulamentos de desempenho comuns num VPS mostra como a falta de memória se traduz em lentidão.
6. Corrija os 502 causados pelo tamanho dos cabeçalhos
Se o registo indicar upstream sent too big header, os cabeçalhos da resposta do upstream são maiores do que o buffer do nginx. Aumente o buffer no bloco location em causa. Os valores abaixo são exemplos; ajuste-os ao tamanho do seu maior cabeçalho.
location / {
proxy_pass http://127.0.0.1:3000;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
}No PHP-FPM, use da mesma forma o fastcgi_buffer_size e o fastcgi_buffers no bloco location que contém o fastcgi_pass [5]. Confirme os valores predefinidos das diretivas e a sintaxe exata na documentação de referência do módulo [4]. Também pode reduzir o tamanho dos cabeçalhos que a aplicação envia, por exemplo cookies demasiado grandes. Depois, teste e recarregue como no passo 4.
7. Verifique a firewall entre o proxy e a origem
Se o proxy estiver noutra máquina, ou se um serviço como a Cloudflare se ligar à sua origem, uma regra de firewall pode bloquear essa ligação. Nesse caso, o proxy não recebe nenhuma resposta utilizável e devolve 502. Confirme que a origem aceita ligações dos endereços do proxy na porta que este usa. No Ubuntu com o ufw:
sudo ufw status verboseSe usar outra firewall, verifique as regras dessa firewall.
502 por trás da Cloudflare
O corpo da página indica que lado gerou o erro. Segundo a Cloudflare, uma página 502 ou 504 com a marca da Cloudflare veio do seu servidor web de origem. Uma página simples, sem a marca, pode vir da própria Cloudflare, mas esta também aponta um problema de compressão na origem como causa de páginas 502 sem marca [7]. Por isso, a marca esclarece a maioria dos casos, mas não todos. Se a página não tiver a marca e a origem responder diretamente com 200, verifique as definições de compressão da origem.
Um 502 prejudica o SEO?
Um 502 de curta duração faz pouco mal. A documentação do Google sobre os seus rastreadores diz que as respostas 5xx e 429 os fazem abrandar. Os URLs que continuam a devolver erros de servidor acabam por ser removidos do índice, embora, numa primeira fase, os URLs indexados se mantenham. O rastreio volta a acelerar quando o servidor devolve de novo respostas 2xx [8].
Na prática: corrija a causa depressa. Um erro que se repete durante muito tempo pode fazer-lhe perder posições nos resultados de pesquisa.
Como evitar erros 502
- Monitorize o site a partir do exterior. Uma verificação externa avisa-o quando o 502 começa, em vez de ser um visitante a comunicá-lo mais tarde. Veja as ferramentas de monitorização da disponibilidade.
- Mantenha RAM suficiente. Os processos terminados por falta de memória provocam as linhas «prematurely closed connection». Se o servidor ficar sem memória com frequência, leia os sinais de que precisa de aumentar os recursos do seu VPS e os problemas comuns de alojamento VPS e as suas soluções.
- Reinicie a aplicação quando esta falhar. Uma unidade systemd com uma política de reinício volta a pôr a aplicação a funcionar depois de uma falha. O
Restart=on-failuresó reinicia o processo quando este termina com um erro. Não corrige o bug que causou a falha, por isso guarde as linhas de registo do passo 2.
[Service]
ExecStart=/usr/bin/node /srv/myapp/server.js
Restart=on-failure
RestartSec=5- Acrescente uma verificação de estado (health check). Crie na aplicação um endpoint que só devolva 200 quando esta conseguir responder a pedidos, e monitorize esse endpoint. Assim, um processo que está em execução mas bloqueado passa a aparecer como falha.
- Saiba onde procurar quando o servidor para. Se o servidor deixar de responder por si só, leia porque é que um servidor para aleatoriamente.
Prepare-se para a próxima falha
Antes de qualquer incidente, anote a porta ou o socket em que a aplicação está à escuta, o caminho dos registos e o comando para a reiniciar. A correção do passo 2 depende da linha de registo exata, e a recuperação mais rápida depende de saber o nome do serviço.
Aplicar a correção por sua conta num VPS da StealthRDP
Os planos Linux da StealthRDP incluem acesso root total: o servidor web e a aplicação ficam a seu cargo e pode seguir todos os passos deste guia no seu próprio servidor. Para comparar planos, veja VPS Linux e planos VPS.
Fontes e referências
- RFC 9110: HTTP Semantics — RFC Editor (IETF) (consultado a 2026-10-10)
- 502 Bad Gateway — MDN Web Docs (Mozilla) (consultado a 2026-10-10)
- 504 Gateway Timeout — MDN Web Docs (Mozilla) (consultado a 2026-10-10)
- Module ngx_http_proxy_module — nginx (consultado a 2026-10-10)
- Module ngx_http_fastcgi_module — nginx (consultado a 2026-10-10)
- PHP: Configuration (FPM) — The PHP Group (consultado a 2026-10-10)
- Error 502 or 504 — Cloudflare (consultado a 2026-10-10)
- How HTTP Status Codes Affect Google's Crawlers — Google (consultado a 2026-10-10)
Continue a ler
Proteção DDoS para VPS: o que verificar e como a configurar
Como avaliar a proteção DDoS para VPS que um fornecedor oferece e montar a sua própria defesa em camadas: firewall, filtragem, monitorização e recuperação.
VPS Windows ou Linux: qual deve escolher para a sua empresa?
VPS Windows ou Linux? Compare licenciamento, consumo de recursos, software, gestão e segurança, e decida rapidamente qual se adapta à sua carga de trabalho.
Upgrade do VPS: 8 sinais de que precisa de mais recursos
Saiba reconhecer os sinais de que precisa de fazer o upgrade do VPS, da lentidão no carregamento aos limites de recursos, e mantenha o seu site rápido.
