Seus usuarios veem isso:
HTTP/1.1 504 Gateway Timeout
{"message": "Endpoint request timed out"}Seu API gateway esperou seu backend responder. Esperou. E desistiu.
O que causa timeouts no API gateway
- Queries de banco de dados lentas: Indice faltando, lock de tabela, pool de conexoes esgotado
- Chamadas a APIs externas que travam: Stripe, Auth0 ou terceiro lento/fora do ar
- Cold starts (serverless): Inicializacao + consulta lenta = timeout
- Backend inalcancavel: DNS, firewall, servidor fora do ar
- Resposta grande demais: JSON massivo que demora para serializar
- Loops infinitos ou deadlocks: Bug de codigo que nunca completa
Limites de timeout por plataforma
| Plataforma | Padrao | Maximo |
|---|---|---|
| AWS API Gateway (REST) | 29s | 29s (limite rigido) |
| Kong | 60s | Sem limite |
| Nginx | 60s | Sem limite |
| Vercel | 10s (Hobby) | 300s (Enterprise) |
Como resolver
- Identificar qual endpoint faz timeoutHabilitar access logs no gateway
- Verificar se o backend e alcancavelTestar conectividade DNS/rede
- Perfilar o endpoint lentoAdicionar timing a cada operacao
- Resolver a causa raizIndices, caching, circuit breakers, pool de conexoes
- Para operacoes inerentemente lentas: Padrao assincrono (202 Accepted + polling)
Como monitorar timeouts antes dos usuarios reportarem
A versao mais simples e um check agendado que mede seus endpoints mais lentos e alerta bem antes do limite do gateway:
// check-latency.ts, rode a cada minuto via cron
const start = Date.now()
const res = await fetch('https://api.example.com/api/reports', {
signal: AbortSignal.timeout(29_000),
})
const ms = Date.now() - start
// notify() = seu webhook do Slack, email ou pager
if (!res.ok || ms > 10_000) await notify(`/api/reports: ${res.status} in ${ms}ms`)Alerte numa fracao do limite (aqui 10 segundos contra um timeout de 29), assim voce tem margem para corrigir antes do gateway comecar a derrubar requests. Em producao, meça tambem a latencia P95 por rota com trafego real (por exemplo com OpenTelemetry).