O que significa um erro 502 Bad Gateway e de quem é a culpa

Um 502 Bad Gateway é um servidor informando que outro servidor, aquele em que estava confiando, respondeu com algo que não consegue usar. Não é “o site está fora do ar” exatamente, e não é “você fez algo errado” de forma alguma: uma máquina no meio pediu à máquina atrás dela por sua página, e o que voltou foi lixo, uma porta fechada, ou nada que fizesse sentido.

A palavra gateway é a pista. O servidor que você alcançou não é o que faz sua página; é uma frente, um proxy reverso ou um balanceador de carga, em pé na frente da aplicação que faz o trabalho real. Quando essa frente recebe uma resposta quebrada de trás dela, a única coisa honesta que pode relatar a você é que a resposta era ruim. Que é exatamente o que 502 significa.

A imagem dos dois servidores

Quase todo site de qualquer tamanho tem pelo menos duas máquinas. Há a que seu navegador se conecta primeiro - nginx, uma borda de CDN, um balanceador de carga em nuvem - e atrás dela o servidor de aplicação que realmente executa o código e constrói a página.

A frente pega sua solicitação e passa para trás. Na maioria das vezes a aplicação responde limpar e a frente entrega essa resposta a você, invisível. Um 502 é o que você vê quando esse segundo passo falha: a frente perguntou, e a resposta que recebeu não era uma resposta HTTP válida que pudesse retransmitir.

Então um 502 nunca é realmente sobre o servidor que você alcançou. É uma mensagem sobre o que você não alcançou.

502 versus 504, que são constantemente confundidos

Eles vêm do mesmo lugar - o servidor de frente, informando sobre o que está atrás dele - e diferenciá-los reduz bastante a causa.

502 Bad Gateway

O upstream respondeu, e a resposta era inutilizável - uma conexão recusada, um processo quebrado, lixo no fio. Geralmente rápido

504 Gateway Timeout

O upstream não respondeu nada dentro do tempo permitido. Geralmente lento, e a pausa antes do erro é em si mesma a pista

Aproximadamente: 502 é “disse algo errado”, 504 é “ainda não disse nada”. Um 502 chega rápido e aponta para algo quebrado, travado ou recusando conexões; um 504 chega devagar e aponta para algo preso ou sobrecarregado. Se o erro voltou quase instantaneamente, é muito mais provável um 502 do que um 504, independentemente do que a página diz.

Uma volta que a maioria dos artigos perde: provedores mudam isso. O Cloudflare retorna 502 quando seu origin envia uma resposta inválida, e seu próprio 520 para uma resposta tão malformada que não cabe em nenhum código padrão. Atrás de um CDN, o número que você vê pode ser a conta do CDN do mesmo evento em vez da sua conta de servidor.

Se você é o visitante

Recarregue uma vez, porque um 502 é frequentemente um único worker quebrado ou um processo pego no meio de um reinício, e a próxima solicitação cai em um saudável. Se limpar, não há nada para perseguir.

Se persistir, a falha está do lado do site e há genuinamente pouco que você possa fazer além de contar a eles, porque nenhuma configuração no seu navegador alcança um processo quebrado no servidor deles. Antes de você assumir que é você, confirme que não é local: a verificação mais rápida é apontar o verificador de status HTTP para o endereço, que solicita a página do nosso servidor em vez do seu e relata o código que voltou. Se ele também vir o 502, o problema não é sua conexão.

Se é o seu site

Um 502 diz que a frente não conseguiu usar o que a aplicação enviou, então a pergunta é o que a aplicação fez. Há apenas algumas respostas comuns.

O processo da aplicação está parado ou travando. A causa mais frequente de longe. A frente tenta se conectar e recebe “conexão recusada” porque nada está ouvindo, ou o processo aceita a solicitação e morre no meio da resposta. Verifique se o app realmente está rodando, e leia seus próprios logs para um travamento ou uma morte por falta de memória no momento do erro - os logs da frente apenas dirão que o upstream falhou, nunca por quê.

Uma incompatibilidade de timeout entre as camadas. Se a aplicação leva mais tempo para responder do que a frente está disposta a esperar, alguns proxies reportam isso como um 502 em vez de um 504, fechando a conexão e chamando a resposta meio completa de ruim. Quando um 502 se correlaciona com solicitações lentas em vez de travamentos, procure aqui.

Um deploy ruim. Uma nova compilação que falha ao iniciar, escuta na porta errada, ou responde com cabeçalhos que a frente rejeita, transformará cada solicitação em um 502 no momento em que ficar online. Se os erros começaram em um deploy, esse é o primeiro lugar para procurar, e um rollback é mais rápido que um diagnóstico.

Algo entre as camadas. Um proxy_pass mal configurado, um nome de host upstream que já não resolve, um grupo de segurança que silenciosamente parou de permitir que a frente alcançasse a aplicação - a conexão nunca completa e a frente reporta um bad gateway. Estes são os mais lentos de encontrar porque nada travou; um link na corrente simplesmente parou de carregar tráfego.

Por que estes são tão difíceis de investigar depois

Um 502 frequentemente desaparece antes que alguém procure. O worker quebrado reinicia, o deploy é feito rollback, o surto de tráfego passa, e o log da frente diz apenas que uma solicitação upstream falhou às 09:14 - não o que o upstream disse, não qual processo, não por quê.

O que resolve é evidência capturada enquanto está acontecendo: a solicitação que falhou, o status exato, o tempo, e o que a pessoa estava fazendo quando apareceu. Um 502 que um usuário reporta uma hora depois, de memória, é um palpite. Um 502 com a solicitação com falha e seu timestamp anexado é uma linha que você pode combinar com o log da aplicação e o histórico de deploy e fechar.

O log de rede contém a solicitação com falha com seu 502 e o momento em que aconteceu, salvo enquanto dava errado em vez de ser lembrado depois - que é a diferença entre um relatório que alguém pode agir e um que ele precisa reproduzir primeiro.

Em um parágrafo

Um 502 Bad Gateway é um servidor de primeira linha informando que o servidor atrás dele deu uma resposta que não conseguiu usar - travado, recusado, ou malformado - e chega rápido, que é o que o diferencia do lento 504. Se você está visitando, recarregue uma vez e depois assuma que é do lado deles. Se é seu, verifique se a aplicação está rodando e o que registrou, desconfie do último deploy se o tempo se ajusta, e capture a solicitação com falha enquanto você a tem, porque um 502 é quase impossível de investigar após ter passado.