API Gateway Timeout: Causas, Soluciones y Como Monitorearlo

Tus usuarios ven esto:

    HTTP/1.1 504 Gateway Timeout
{"message": "Endpoint request timed out"}

Tu API gateway espero a que tu backend responda. Espero. Y espero. Y se rindio.

Que causa timeouts en el API gateway

• Queries de base de datos lentas: Indice faltante, lock de tabla, pool de conexiones agotado
• Llamadas a APIs externas que cuelgan: Stripe, Auth0 o un tercero lento/caido
• Cold starts (serverless): Inicializacion + consulta lenta = timeout
• Backend inalcanzable: DNS, firewall, servidor caido
• Respuesta demasiado grande: JSON masivo que tarda en serializar
• Loops infinitos o deadlocks: Bug de codigo que nunca completa

Limites de timeout por plataforma

Como solucionarlo

1. Identificar que endpoint hace timeout — Habilitar access logs en el gateway
2. Verificar si el backend es alcanzable — Testear conectividad DNS/red
3. Perfilar el endpoint lento — Agregar timing a cada operacion (DB, API externa, transformacion)
4. Solucionar la causa raiz — Indices, caching, circuit breakers, pool de conexiones
5. Para operaciones inherentemente lentas: Patron asincrono (202 Accepted + polling)

Como monitorear timeouts antes que los usuarios los reporten

Nurbak Watch monitorea cada API route desde dentro de tu servidor Next.js y te alerta cuando la latencia sube — antes de que cruce el umbral de timeout del gateway.

    // instrumentation.ts
import { initWatch } from '@nurbak/watch'

export function register() {
  initWatch({
    apiKey: process.env.NURBAK_WATCH_KEY,
  })
}

Gratis durante la beta. Sin agentes, sin overhead de cold start. 5 lineas de codigo.