De Olho

erro 502 bad gateway

Erro 502: alguém à frente respondeu por quem está atrás.

O 502 nunca é um erro do site — é um intermediário a dizer que pediu a página a outro servidor e não recebeu resposta válida. A pergunta útil não é o que correu mal, é qual das camadas é que se calou.

Um site moderno raramente é um servidor só. Há um proxy à frente (Nginx), muitas vezes uma CDN à frente disso (Cloudflare), e o PHP ou o Node a correr atrás. O 502 é a camada da frente a dizer que fez o pedido à camada de trás e recebeu lixo, ou não recebeu nada.

A diferença para um 500 é toda: no 500 o teu código rebentou; no 502 o teu código pode estar impecável e não ter sequer chegado a correr. O que falhou foi a conversa entre duas máquinas — ou o processo de trás, que morreu e ainda não voltou.

Isto tem uma consequência prática que muda o diagnóstico: o 502 é frequentemente parcial. Se vem de uma CDN, um nó em Lisboa pode devolver 502 enquanto um nó em Frankfurt serve a página guardada em cache. Duas pessoas a olhar para o mesmo site vêem coisas diferentes, e ambas têm razão.

// a ficha

O que este código diz, em cinco linhas.

Código
502 Bad Gateway
Família
5xx — erro do servidor
Quem responde
o proxy, o CDN ou o balanceador da frente
Quem falhou
o servidor de trás, ou a ligação até ele
Aparece a toda a gente
depende do nó — pode ser só numa região

// causas prováveis

Por onde é que isto costuma vir.

Por ordem de frequência e não por ordem de gravidade. A primeira da lista explica mais casos do que as outras todas juntas.

  • O PHP-FPM ou o Node caíram e não reiniciaram

    O processo de trás morreu — por falta de memória, por um erro fatal ou porque o gestor de processos o matou. O Nginx continua de pé e responde 502 a tudo. É a causa mais comum em VPS e em alojamento gerido.

  • O servidor de trás demorou de mais e a ligação foi cortada

    Um pedido que passa dos segundos configurados no proxy é abortado. Uma consulta lenta à base de dados, uma importação, um cron pesado — o resultado é 502 em vez de 504 quando a ligação é cortada em vez de expirar.

  • A Cloudflare não conseguiu falar com a origem

    Se usas Cloudflare, o 502 pode ser dela e não do teu servidor. Os erros 520 a 526 são a versão detalhada disto — vale a pena ver qual apareceu, porque cada número aponta para uma causa diferente.

  • Um pico de tráfego esgotou os processos disponíveis

    O `pm.max_children` do PHP-FPM tem um tecto. Cheio esse tecto, os pedidos seguintes ficam em fila e depois falham. Vê-se sempre à mesma hora, ou sempre que sai uma campanha.

  • Uma actualização a meio

    Um deploy que reiniciou o serviço, uma actualização do PHP no painel do alojamento. São 502 de trinta segundos que ninguém vê — a não ser que alguém esteja a verificar ao minuto.

// diagnóstico

Passo a passo, do que custa menos ao que custa mais.

Cada passo elimina hipóteses. Saltar um passo poupa dois minutos e costuma custar uma hora — a ordem é a parte que interessa.

  1. 01

    Vê se o 502 é para todos ou só para ti

    Verifica de fora, a partir de um servidor que não seja a tua rede. Se a verificação externa devolver 200 e tu vires 502, estás a apanhar um nó de CDN estragado — e a correcção é outra. O "Está em baixo, ou és só tu?" responde a isto em segundos.

  2. 02

    Identifica quem devolveu o erro

    A página de erro diz quase sempre quem a escreveu: "nginx", "cloudflare", o nome do alojamento. Isso diz-te em que camada estás. Um 502 com marca da Cloudflare é um problema entre ela e a tua origem; um 502 do Nginx é entre o Nginx e o PHP.

  3. 03

    Contorna a CDN e pede à origem directamente

    Se há Cloudflare pelo meio, testa o IP de origem directamente com um `curl` e o cabeçalho `Host` certo, ou aponta o teu ficheiro `hosts` para lá. Se a origem responder 200, o problema está na frente e não no site.

  4. 04

    Olha para o estado do processo de trás

    Num VPS: `systemctl status php-fpm` ou o equivalente para Node. Em alojamento partilhado não tens isto — o equivalente é abrir um pedido ao suporte com a hora exacta, porque eles vêem-no no log deles.

  5. 05

    Procura o erro no log do proxy

    O log de erros do Nginx diz a razão em texto simples: "connect() failed", "upstream prematurely closed connection", "no live upstreams". Cada uma dessas frases aponta para uma causa diferente e poupa-te horas de adivinhação.

  6. 06

    Se voltou sozinho, não deixes o assunto morrer

    Um 502 que desaparece antes de ser diagnosticado costuma voltar à mesma hora. Regista quando aconteceu. Sem registo, o terceiro incidente é tão surpreendente como o primeiro.

O primeiro passo é sempre o mesmo — ver de fora o que o servidor responde de facto. Faz isso aqui, a partir de um servidor em Portugal. Sem conta, sem custo, e não guardamos o que verificares.

verificar_site servidor: PT

// que não volte

Como evitar que volte a acontecer sem dares por isso.

Resolver o incidente é metade do trabalho. A outra metade é a parte que ninguém factura e é a que decide se há um terceiro.

  • Põe o processo de trás a reiniciar sozinho

    Um `Restart=always` no serviço de systemd transforma um incidente de duas horas num de vinte segundos. Não resolve a causa — resolve a duração, que é o que o cliente sente.

  • Sobe os limites antes de os atingires

    O `pm.max_children` e os timeouts do proxy foram configurados quando o site tinha outro tráfego. Revê-os quando o site crescer, e não no dia em que estourarem.

  • Separa o que é lento do que serve páginas

    Importações, envios de email em massa e relatórios não deviam correr no mesmo processo que responde aos visitantes. Uma fila ou um cron tira-os do caminho.

  • Mede a duração, não só a ocorrência

    A maior parte dos 502 dura menos de cinco minutos, que é exactamente o intervalo das ferramentas gratuitas de monitorização. Passam despercebidos até o dia em que um deles dura duas horas.

// limites

Onde é que esta página encalha.

Uma página de diagnóstico que não diz onde acaba manda-te dar voltas até desistires. Estes são os casos em que não chega.

  • Em alojamento partilhado não chegas ao log do Nginx nem ao estado do PHP-FPM. Metade destes passos exige acesso que não tens, e o caminho honesto é abrir um pedido com a hora exacta do erro.
  • Um 502 intermitente é dos problemas mais difíceis de provar. Se dura noventa segundos, é preciso estar a olhar no momento certo — ou ter um registo que estivesse.
  • Se o erro vem da Cloudflare com um código 5xx próprio (520, 521, 522), esta página não chega. Esses números têm significados específicos e a documentação deles é o sítio certo.
  • Não dizemos qual é a configuração certa para o teu servidor. Os números certos dependem da memória, do tráfego e do que o site faz — o que dá para dizer é onde olhar.

// perguntas

O que nos perguntam a seguir.

Qual é a diferença entre 502 e 504?

Os dois são o intermediário a queixar-se de quem está atrás. No 502 a resposta que chegou não era válida, ou a ligação foi cortada; no 504 não chegou resposta nenhuma dentro do tempo permitido. Na prática, o 504 é quase sempre lentidão e o 502 é quase sempre um processo morto.

O 502 é culpa do meu alojamento?

Muitas vezes sim, e é uma das poucas situações em que vale mesmo a pena abrir um pedido de suporte cedo. Mas também pode ser código teu a esgotar recursos. O log do proxy é o que separa os dois casos, e sem ele a conversa fica em suposições de parte a parte.

Limpar a cache resolve um 502?

Às vezes parece resolver, e o que aconteceu foi outra coisa: o processo de trás recuperou entretanto. Se o 502 desaparece ao limpar a cache do browser, a hipótese mais provável é ter sido coincidência.

// erros vizinhos

Se afinal não era este.

Metade do diagnóstico é perceber que se estava a olhar para o erro errado. Estes três são os que mais se confundem com este.

E se acontecer às três da manhã?

A característica desagradável do 502 é a duração: a maior parte deles resolve-se sozinha em minutos, e é precisamente por isso que ninguém dá por eles — até ao dia em que um dura duas horas de manhã. A De Olho vai verificar ao minuto e guardar cada incidente com a hora de início e de fim, o que transforma "às vezes o site vai abaixo" numa lista de datas que dá para mostrar ao alojamento.

A De Olho abre em 2026 e ainda não dá para usar. Quem estiver na lista de espera fica a saber primeiro e mantém o preço de lançamento enquanto a subscrição durar.

Só te escrevemos sobre o lançamento. Sem spam, e não partilhamos o teu email com ninguém. Como tratamos os teus dados.