Erro 504 no Nginx? Como tunar timeouts e conexões upstream

O que causa o temido erro 504 no Nginx e como ele afeta seus usuários

Quando um usuário tenta acessar sua aplicação e se depara com a tela de falha, o servidor web geralmente está funcionando, mas a comunicação interna sofreu uma ruptura. Na prática, isso significa que o Nginx, atuando como um proxy reverso, repassou a requisição para o servidor de aplicação por trás dele, mas o tempo limite estipulado esgotou antes que houvesse uma resposta de retorno. Esse cenário costuma aparecer em picos de tráfego ou em operações pesadas que exigem alto poder de processamento interno.

Para quem acompanha a operação, o erro 504 Gateway Timeout é frustrante porque ele esconde onde está o verdadeiro gargalo. O servidor intermediário simplesmente desiste de esperar após um período padrão de sessenta segundos, jogando a toalha. Compreender essa dinâmica é o primeiro passo para evitar quedas abruptas de conexão e garantir que aplicações web robustas consigam absorver tráfego intenso sem perder requisições críticas no meio do caminho.

Ajustando timeouts de proxy para evitar desistências prematuras

O Nginx possui diretivas específicas que controlam quanto tempo ele deve aguardar em cada etapa da comunicação com o servidor de aplicação. Por padrão, esses limites podem ser curtos demais para rotinas complexas que envolvem relatórios pesados, processamento de pagamentos ou integrações lentas. Modificar esses parâmetros exige cautela para não mascarar problemas reais de lentidão no código.

No arquivo de configuração, você precisa tunar três diretivas principais: o proxy_connect_timeout, que define o tempo para estabelecer conexão com o backend; o proxy_send_timeout, que controla o envio de dados; e o proxy_read_timeout, o mais importante para evitar o erro 504, que determina quanto tempo o Nginx espera por uma resposta após enviar a requisição. Ajustar esses valores evita que o servidor desista cedo demais de tarefas legítimas que apenas demoram um pouco mais para rodar.

Otimizando o pool de conexões com upstream e keepalive

Além do tempo limite, o gerenciamento de conexões entre o Nginx e o servidor de aplicação dita a performance geral do sistema sob alta concorrência. Se cada requisição precisar abrir uma nova conexão TCP do zero, o consumo de recursos dispara e o sistema sofre com gargalos de rede, problemas semelhantes aos que encontramos ao gerenciar condições de corrida e deadlocks em ambientes concorridos.

A diretiva keepalive combinada com o bloco upstream permite reutilizar conexões já estabelecidas, reduzindo drasticamente a latência e o uso de portas efêmeras no sistema operacional. Na prática, isso mantém um túnel aberto e pronto para uso imediato, agilizando o fluxo de dados entre as camadas da infraestrutura sem sobrecarregar o hardware disponível.

upstream meu_backend {
    server 127.0.0.1:8080 max_fails=3 fail_timeout=10s;
    keepalive 32;
}

server {
    listen 80;
    server_name meuapp.local;

    location / {
        proxy_pass http://meu_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

Identificando gargalos reais na aplicação para além do Nginx

Aumentar o tempo limite no Nginx resolve o sintoma imediato, mas muitas vezes esconde um problema crônico de performance no código da aplicação ou no banco de dados. Se uma consulta SQL mal indexada demora dois minutos para rodar, o erro 504 voltará a acontecer assim que o tráfego dobrar, mostrando que apenas mexer no proxy não substitui uma boa engenharia de software.

Ferramentas de monitoramento de performance e logs detalhados ajudam a mapear quais rotas específicas estouram o tempo limite. Descobrir se a lentidão vem de chamadas externas a APIs de terceiros, gargalos de disco ou uso excessivo de memória permite corrigir a raiz do problema, garantindo que o sistema responda rapidamente sem depender de timeouts excessivamente longos. Para aprofundar esses conceitos na prática em produção, confira também nossa análise técnica sobre IA instável? Como usar guardrails para validar saídas de LLMs.

Considerações finais sobre estabilidade e resiliência web

Tunagem de servidores web é um exercício constante de equilíbrio entre tolerância a falhas e eficiência operacional. Ajustar os timeouts do Nginx e otimizar conexões upstream garante que sua infraestrutura aguente rajadas de tráfego sem derrubar conexões legítimas, melhorando a experiência de quem utiliza a aplicação todos os dias.

Manter uma cultura de monitoramento ativo e testes de carga regulares assegura que qualquer alteração de configuração traga ganhos reais de estabilidade, preparando seu ambiente para crescer de forma sustentável e previsível.