O Que É um 502 Bad Gateway? Respostas Quebradas do Upstream
Um 502 Bad Gateway é um erro HTTP retornado por um proxy ou load balancer quando ele tentou alcançar um servidor upstream mas recebeu uma resposta inválida ou nenhuma resposta de volta.
Um 502 não vem da sua aplicação; vem do proxy na frente dela dizendo que o backend falhou em responder adequadamente. Como deploys reciclam backends, 502s comumente aparecem por alguns segundos durante um rollout. Saber disso te poupa de caçar um bug de aplicação que na verdade é uma questão de timing.
Um erro no nível do proxy
Um reverse proxy, gateway ou load balancer retorna 502 quando encaminha uma requisição para o upstream e recebe uma resposta quebrada, vazia ou não parseável. O proxy está saudável; o backend é o problema.
Causas comuns
- O backend travou ou está reiniciando.
- Nenhum backend saudável foi registrado ainda.
- O upstream fechou a conexão inesperadamente.
Por que deploys acionam 502s
Durante um rollout, instâncias antigas drenam enquanto novas iniciam. Por uma breve janela o proxy pode encaminhar para uma instância que não está pronta, produzindo 502s transitórios até a nova versão estar servindo totalmente.
502 versus 503 versus 504
Um 502 significa uma resposta ruim do upstream, um 503 significa que nenhum backend está disponível, e um 504 significa que o upstream atingiu timeout. A distinção te aponta para a causa certa durante um deploy.
502s em verificações de CI
Um smoke check pós-deploy que roda no instante em que o tráfego migra pode pegar um 502 transitório. Aguardar os health checks passarem antes de verificar evita esse alarme falso.
Transitório e passível de retry
Um 502 na janela de deploy é quase sempre transitório e se resolve assim que os backends ficam saudáveis. Os runners da Latchkey fazem retry de 502s transitórios a endpoints comuns durante a verificação de deploy, para que uma lacuna momentânea de rollout não faça a etapa falhar.
Principais conclusões
- Um 502 Bad Gateway significa que um proxy recebeu uma resposta inválida do backend upstream.
- Ele surge brevemente durante deploys conforme backends drenam e iniciam.
- Um 502 na janela de deploy é transitório e passível de retry, ao contrário de um persistente.