reverse proxy em APIs backend: erros que geram falhas, lentidão ou retrabalho

Reverse proxy em APIs backend: erros que causam falhas, lentidão e retrabalho

Como identificar problemas de roteamento, headers, timeouts e conexões no Nginx antes de alterar o backend sem necessidade.

Uma API funciona no acesso interno, mas retorna erros pelo domínio público. Um endpoint entrega eventos imediatamente na aplicação, porém o cliente os recebe em blocos. Uma exportação termina no servidor depois que o navegador já recebeu um timeout.

Esses sintomas exigem investigar o caminho completo da requisição. A configuração de reverse proxy em APIs backend pode modificar rotas, perder contexto de HTTPS ou impor limites incompatíveis com a operação. A aplicação também pode estar lenta, indisponível ou saturada.

O roteiro a seguir ajuda a distinguir essas situações, reunir evidências e validar uma correção antes de publicá-la.

Antes de corrigir: descubra em qual camada a API falha

Desenhe o trajeto real: cliente, eventuais CDN e balanceadores, Nginx, servidor da aplicação e dependências. O upstream é o destino ao qual o Nginx encaminha a chamada; ele pode ser outra camada intermediária.

Para uma requisição problemática, registre método, caminho, query string, headers relevantes, status e duração. Preserve o horário e um identificador que permita encontrar a chamada nos logs. Não copie credenciais para relatórios de diagnóstico.

Compare o acesso público com o acesso ao upstream a partir do ambiente do proxy ou de uma rede equivalente. O exemplo abaixo usa endereços ilustrativos e pressupõe que o backend espera o mesmo caminho:

curl -sS -o /dev/null -w 'status=%{http_code} total=%{time_total}\n' \
  'https://api.exemplo.test/api/pedidos?limite=10'

curl -sS -o /dev/null -w 'status=%{http_code} total=%{time_total}\n' \
  -H 'Host: api.exemplo.test' \
  'http://backend:8000/api/pedidos?limite=10'

Se a chamada exige autenticação, use o mesmo contexto de acesso nas duas comparações. Caso o proxy remova um prefixo, ajuste o teste interno ao caminho efetivamente encaminhado. Diferenças de TLS, cache, rede e volume de tráfego também precisam entrar na análise.

O status HTTP orienta a investigação, mas não identifica sozinho a causa. Um erro 502 no Nginx pode envolver conexão recusada ou resposta inválida do upstream. Um 504 pode indicar espera excedida. Verifique qual camada produziu a resposta e relacione o access log, o error log e os registros da aplicação.

Erros em location e proxy_pass que alteram rotas da API

Um encaminhamento incorreto pode produzir um 404 perfeitamente válido no backend. Antes de modificar o controlador da API, confirme qual caminho chegou à aplicação.

Neste exemplo simples de location por prefixo, sem regex, variáveis ou reescrita, a ausência de URI no proxy_pass preserva o caminho:

location /api/ {
    proxy_pass http://backend;
}
# /api/pedidos chega como /api/pedidos

Ao incluir a URI / no destino, a parte correspondente ao prefixo é substituída:

location /api/ {
    proxy_pass http://backend/;
}
# /api/pedidos chega como /pedidos

Nesses casos, uma query como ?pagina=2 continua sendo encaminhada. A diferença da barra decorre da presença de uma URI no destino; não é uma regra universal de remoção de prefixos.

Inspecione também locations exatos, expressões regulares e regras de rewrite. Eles podem mudar o bloco selecionado ou a URI encaminhada. Configurações com variáveis exigem análise específica.

Monte uma pequena matriz com /api, /api/, um recurso válido, um inexistente e parâmetros de consulta. Registre o destino esperado e o observado. Para aprofundar essa configuração, consulte o guia de implementação de reverse proxy em APIs backend.

Upstreams inacessíveis: endereço, porta, DNS e TLS

Teste endereço e porta a partir do ambiente em que o Nginx executa. Uma conexão bem-sucedida no notebook não comprova conectividade dentro do contêiner do proxy.

Um erro recorrente é usar localhost:8000 quando a API está em outro contêiner. Em ambientes com redes isoladas, esse endereço aponta para o próprio contêiner do Nginx. Verifique o nome do serviço, a rede compartilhada e a porta interna da aplicação.

• Confirme em qual interface e porta a aplicação escuta.
• Teste a resolução do nome dentro do ambiente do proxy.
• Verifique regras de rede, firewall e disponibilidade do processo.
• Compare o endereço registrado em upstream_addr com o destino esperado.

Em serviços que mudam de IP, confira como a configuração de upstream atualiza a resolução DNS. O comportamento depende da versão, das diretivas usadas e da forma de declarar o destino. Não presuma que a atualização acontece a cada requisição.

Se a conexão com o upstream usa HTTPS, investigue também SNI, nome esperado no certificado, cadeia de confiança e validação TLS. Uma falha de negociação acontece antes de a aplicação tratar a rota. Desativar a verificação do certificado como solução permanente elimina uma proteção e deixa a causa sem correção.

Headers incorretos quebram redirects, cookies e identificação do cliente

Quando o Nginx termina TLS e conversa por HTTP com a aplicação, o backend precisa receber o contexto original. Caso contrário, pode gerar URLs com esquema incorreto ou entrar em um ciclo de redirecionamento para HTTPS.

Os headers de proxy transportam informações distintas: Host identifica o host solicitado, X-Forwarded-Proto informa o protocolo original e X-Forwarded-For representa a cadeia de endereços encaminhados. O header padronizado Forwarded também pode transportar esse contexto, conforme o suporte da infraestrutura e do framework.

Para uma topologia simples, em que o Nginx recebe diretamente o tráfego público e termina HTTPS, este fragmento estabelece valores a partir da conexão recebida:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;

Esse exemplo sobrescreve o histórico de IP enviado pelo cliente. Em uma cadeia com CDN ou balanceador, defina quais intermediários são confiáveis e como preservar o endereço original. Usar $scheme nesse cenário pode informar apenas o protocolo entre o balanceador e o Nginx.

Configure o framework para confiar nos proxies efetivamente usados. Aceitar indiscriminadamente headers enviados pela internet permite falsificar informações de origem. Valide redirects, URLs absolutas e atributos dos cookies após qualquer alteração nessa fronteira.

Timeouts desalinhados causam 504 e escondem gargalos

Aumentar um timeout no reverse proxy pode apenas prolongar a espera por uma operação saturada. Primeiro, identifique a etapa que excedeu o limite:

Os dois últimos não representam necessariamente um prazo total para a chamada. Uma resposta que continua enviando dados pode permanecer aberta por mais tempo que o valor configurado.

Considere uma exportação que consulta o banco durante um período prolongado sem produzir dados. Se o intervalo sem resposta ultrapassar o limite de leitura, o proxy poderá encerrar a espera enquanto o backend continua trabalhando. Correlacione o evento com consultas, chamadas externas e filas da aplicação.

Mapeie os limites do cliente, balanceador, Nginx, servidor da aplicação e dependências. Defina prazos e cancelamento para evitar trabalho sem consumidor. Quando a operação ultrapassa o tempo aceitável de resposta, avalie uma tarefa assíncrona com consulta posterior de estado.

Em ambientes PHP, investigue também a capacidade e os limites do pool: o conteúdo sobre erros de PHP-FPM em APIs em produção aborda esse componente relacionado. Nessa integração, diferencie as diretivas fastcgi_* das diretivas proxy_* usadas para upstreams HTTP.

Conexões e concorrência mal dimensionadas aumentam a latência

Existem conexões entre cliente e Nginx e conexões entre Nginx e upstream. A reutilização em um trecho não comprova reutilização no outro.

Ao revisar keepalive com upstreams HTTP, confira a versão do protocolo e o header Connection. Para uma configuração HTTP/1.1 explícita, um fragmento comum é:

proxy_http_version 1.1;
proxy_set_header Connection "";

Esse fragmento deve ser combinado com a política de keepalive do upstream e com o suporte da aplicação. Não o trate como configuração completa nem como ajuste adequado para WebSocket.

O cache de conexões ociosas de keepalive não é um limite global de concorrência. Revise workers, worker_connections, descritores de arquivos e capacidade do backend. Uma requisição em proxy normalmente envolve conexões nos dois lados, e conexões ociosas também consomem recursos.

Compare carga constante com rajadas. Meça vazão, erros, conexões ativas e percentis p50, p95 e p99 de latência. Observe também filas de workers e pools de banco. Aumentar a concorrência admitida pelo proxy pode piorar a latência em APIs backend quando a aplicação já está no limite.

Buffering e limites inadequados prejudicam uploads e streaming

Uploads e respostas contínuas têm necessidades diferentes das chamadas curtas de JSON. Separe o recebimento do corpo da requisição do envio da resposta.

proxy_request_buffering controla o buffering do corpo enviado ao upstream. proxy_buffering controla o buffering da resposta recebida dele. Alterar um não resolve automaticamente um problema no outro.

Para erros 413, compare client_max_body_size com os limites das outras camadas e da aplicação. Teste arquivos abaixo e acima do tamanho permitido. Em transferências grandes, acompanhe memória, permissões e espaço dos diretórios temporários.

Se um endpoint SSE produz eventos gradualmente, mas o cliente os recebe em blocos, teste com curl -N e compare o acesso direto com o público. Investigue buffering de resposta, compressão, flush da aplicação e comportamento de intermediários. Avalie desativar buffering apenas no endpoint que precisa desse comportamento.

Verifique ainda os intervalos sem eventos: heartbeats precisam chegar antes dos limites de inatividade aplicáveis.

WebSocket exige tratamento próprio de upgrade. Confira o encaminhamento de Upgrade e Connection, a negociação inicial e os períodos de inatividade. Abrir a conexão com sucesso não comprova que ela permanecerá estável durante o uso.

Cache, retries e CORS podem alterar o comportamento da API

Cache exige critérios de elegibilidade e isolamento

Defina quais endpoints podem ser armazenados e quais contextos alteram a resposta: autenticação, cookies, tenant, idioma e parâmetros. Uma chave incompleta pode entregar a representação errada ao cliente.

Revise leitura e gravação do cache, regras herdadas e headers de resposta. A existência de credenciais não substitui a revisão da configuração efetiva. Comece por endpoints explicitamente elegíveis e teste chamadas de usuários distintos.

Se a aplicação também mantém seu próprio cache, separe as duas camadas durante o diagnóstico. O artigo sobre erros de cache aside em APIs de leitura intensa complementa a investigação desse padrão na aplicação.

Retries precisam considerar efeitos já executados

Uma conexão pode cair depois de o backend confirmar uma operação no banco. Repetir a chamada nessa situação pode duplicar um pedido, mesmo que o cliente nunca tenha recebido a primeira resposta.

Revise proxy_next_upstream, condições de falha, quantidade de tentativas e orçamento total de espera. Não habilite repetição de operações não idempotentes sem compreender suas consequências.

Em uma criação de pedido, uma chave de idempotência exige implementação no backend, associação ao conteúdo da operação e controle de concorrência. Acrescentar um header no Nginx, isoladamente, não oferece essa garantia.

CORS precisa de uma política coerente

Defina onde a política será mantida e evite headers conflitantes entre proxy e aplicação. Teste preflight, métodos, headers permitidos e credenciais no navegador. Uma chamada bem-sucedida com curl não comprova que a política CORS está correta.

Logs que ajudam a separar lentidão do proxy e do backend

Registre o endereço e os tempos do upstream junto ao resultado entregue ao cliente. O exemplo abaixo deve ser declarado no contexto http; adapte o caminho do arquivo ao ambiente:

log_format api_timing
    'rid=$request_id method=$request_method uri=$uri '
    'status=$status rt=$request_time '
    'upstream=$upstream_addr us=$upstream_status '
    'uct=$upstream_connect_time '
    'uht=$upstream_header_time '
    'urt=$upstream_response_time';

access_log /var/log/nginx/api_access.log api_timing;

No bloco que encaminha à aplicação, envie o identificador e configure o backend para registrá-lo:

proxy_set_header X-Request-ID $request_id;

• request_time: duração observada pelo Nginx no atendimento da requisição.
• upstream_connect_time: tempo de estabelecimento da conexão, incluindo a negociação TLS quando aplicável.
• upstream_header_time: tempo até receber os headers do upstream.
• upstream_response_time: tempo de recebimento da resposta do upstream.
• upstream_status e upstream_addr: resultado e destino das tentativas.

Conexão rápida e demora até os headers sugerem investigar espera e processamento no caminho do upstream. Demora na conexão direciona a análise para conectividade, negociação ou capacidade de aceitar conexões. Confirme as hipóteses com métricas e logs da aplicação.

Esses tempos não isolam o processamento interno do backend. Também não devem ser somados como etapas independentes. A diferença entre tempo total e tempo de upstream, sozinha, não mede o custo de CPU do Nginx.

Campos com - podem indicar informação indisponível. Múltiplos valores podem representar tentativas ou destinos sucessivos; preserve sua ordem na análise. O exemplo omite query string, mas caminhos também podem conter dados sensíveis. Aplique controle de acesso e retenção aos logs.

Checklist para corrigir e publicar sem gerar retrabalho

Transforme a hipótese em uma mudança pequena, com resultado esperado e critério de reversão. Alterar rota, timeout e concorrência ao mesmo tempo dificulta descobrir o que resolveu o problema.

1. Reproduza o sintoma. Registre a chamada, os horários, os erros e uma linha de base de latência.
2. Inspecione a configuração efetiva. Use nginx -T no ambiente correto e confira includes e parâmetros de inicialização. Proteja a saída, que pode conter informações sensíveis.
3. Confirme o caminho até o upstream. Verifique URI, endereço, porta, headers e protocolo.
4. Aplique a menor correção suficiente. Preserve a configuração anterior pelo processo de versionamento e implantação adotado.
5. Valide a configuração. Execute nginx -t com o binário e os arquivos usados pelo serviço. Esse teste não comprova conectividade nem saúde da API.
6. Faça testes funcionais representativos. Inclua rotas, autenticação, redirects, parâmetros, uploads e conexões persistentes utilizados pelo sistema.
7. Publique pelo processo do ambiente. Quando aplicável, faça a recarga com nginx -s reload e confirme nos logs que a nova configuração foi aceita.
8. Compare o comportamento após a mudança. Acompanhe 404, 502, 504, vazão e percentis de latência em uma janela com tráfego representativo.

Em uma correção de proxy_pass, por exemplo, confirme primeiro a URI recebida pelo backend em homologação. Depois, teste autenticação e redirects, publique e observe se a queda dos 404 veio acompanhada de estabilidade nos demais indicadores.

Use este checklist na próxima investigação de falhas da sua API e explore os conteúdos relacionados do blog Max Alex para aprofundar a configuração do Nginx e a observabilidade do backend.