Erros 502, 503 e 504: o que cada um realmente significa

502, 503 e 504 significam aproximadamente “o servidor não conseguiu lhe dar uma resposta real no momento”, e é por isso que eles são frequentemente confundidos um com o outro. Mas cada código restringe o problema de maneira diferente, e ler o número corretamente economiza tempo na solução de problemas na camada errada.

A distinção rápida

• 502 Bad Gateway — um servidor agindo como gateway ou proxy obteve uma resposta inválida do servidor por trás dele.
• 503 Serviço indisponível — o servidor está ativo, mas se recusa deliberadamente a atender a solicitação no momento (sobrecarregado ou em manutenção).
• 504 Gateway Timeout — um servidor agindo como gateway ou proxy não obteve resposta do servidor por trás dele dentro do limite de tempo.

O padrão: 502 e 504 envolvem dois servidores — um proxy/balanceador de carga/CDN na frente e um servidor de aplicativos atrás dele. 503 geralmente é apenas um servidor informando diretamente que não está pronto.

502 Gateway inválido

O que está acontecendo: Um proxy reverso, balanceador de carga ou CDN (como Cloudflare ou Nginx atuando como gateway) encaminhou sua solicitação para o servidor de aplicativos real e recebeu uma resposta que não conseguiu entender ou que estava malformada — não silêncio, mas uma resposta realmente quebrada.

Causas comuns:

• O servidor de aplicativos (Node, PHP-FPM, um processo de back-end) travou ou reiniciou no meio da solicitação.
• Um proxy reverso mal configurado apontando para a porta ou endereço errado.
• O back-end retornou uma resposta que viola a formatação HTTP básica.
• Um CDN ou WAF na frente do site está configurado incorretamente e rejeitando uma resposta de back-end legítima.

O que verificar se for o seu site: Verifique se há falhas ou reinicializações nos registros do servidor de aplicativos na hora do erro. Confirme se sua configuração de proxy reverso (nginx proxy_pass, destino do balanceador de carga, etc.) aponta para um back-end que está realmente em execução na porta esperada.

503 Serviço indisponível

O que está acontecendo: O servidor recebeu sua solicitação sem problemas, mas está lhe dizendo explicitamente que não pode lidar com ela no momento. Ao contrário do 502/504, isso geralmente é intencional — um servidor declarando sua própria condição, em vez de um proxy reclamando do que está por trás dele.

Causas comuns:

• Manutenção planejada — muitas plataformas retornam 503 propositalmente durante a implantação ou atualização, geralmente com um cabeçalho Retry-After.
• Sobrecarga — muitas solicitações simultâneas para a capacidade do servidor, comum durante picos de tráfego (uma venda, uma postagem viral, um DDoS).
• Esgotamento de recursos — o servidor ficou sem memória, conexões de banco de dados ou processos de trabalho para lidar com novas solicitações.
• Limitação de taxa — algumas configurações retornam 503 em vez de 429 quando um cliente (ou um serviço upstream) está enviando solicitações muito rápido.

O que verificar se for o seu site: Se isso aparecer durante uma implantação, poderá ser resolvido em segundos ou minutos. Se persistir, verifique o uso de recursos do servidor (CPU, memória, limites do pool de conexões) e os logs do seu gerenciador de processos para que os trabalhadores não sejam iniciados ou sejam eliminados.

504 Tempo limite do gateway

O que está acontecendo: A mesma configuração de dois servidores do 502, mas em vez de obter uma resposta interrompida do back-end, o proxy não obteve nada dentro do tempo de espera alocado. É o irmão “gateway” de um tempo limite de conexão simples.

Causas comuns:

• O back-end está demorando muito para processar a solicitação — uma consulta lenta ao banco de dados, um script não otimizado ou uma dependência (API, serviço de terceiros) que é lenta ou lenta.
• O back-end está sobrecarregado e ocupado demais para responder a tempo, mesmo que não tenha travado.
• Uma configuração de tempo limite de proxy que é muito agressiva para uma operação legitimamente lenta (mas funcional), como um upload de arquivo grande ou uma geração pesada de relatórios.

O que verificar se é o seu site: Crie um perfil do endpoint lento diretamente, ignorando o proxy, para ver se o back-end em si é lento ou se o problema está puramente na camada de proxy. Verifique se uma dependência específica (banco de dados, API externa) está degradada, já que essa é a causa raiz mais comum de um back-end ficar lento em vez de travar completamente.

É você ou são eles?

Todos os três são erros do lado do servidor por definição – eles não são causados pelo seu navegador, seu DNS ou sua rede local, o que os separa claramente de problemas como ERR_CONNECTION_TIMED_OUT ou DNS_PROBE_FINISHED_NXDOMAIN. Se você estiver vendo um 502, 503 ou 504, a correção (se houver uma que você possa fazer) quase nunca está disponível - a atualização ocasionalmente funciona para um 503 transitório, mas uma correção persistente significa apenas esperar que o site o resolva.

Para confirmar que não é só você – alguns CDN ou nós de borda regionais ocasionalmente apresentam um erro de gateway incorreto, enquanto outros estão bem – execute o site por meio de uma verificação de status independente para ver o código de status HTTP ativo de um servidor fora de sua própria rede, junto com o tempo de resposta e o status SSL na mesma visualização.