Error 504 Gateway Timeout: Causas y Cómo Resolverlo

El error 504 Gateway Timeout ocurre cuando un gateway o proxy no recibe la respuesta del servidor de origen dentro del plazo. Se diferencia del 502: en el 504, el intermediario esperó, pero no recibió una respuesta HTTP a tiempo. La investigación debe seguir la solicitud de fuera hacia adentro.

Respuesta directa: cómo corregir 504

Registra hora, ruta e ID de solicitud; confirma qué proxy respondió; prueba el origen directamente; compara los timeouts; examina la duración de la aplicación, consultas a la base de datos y llamadas externas. Corrige el trabajo lento o conviértelo en una tarea asíncrona. Aumentar el timeout es una medida temporal cuando la duración larga es legítima y controlada.

Paso 1: dibuja el camino de la solicitud

navegador -> CDN/WAF -> balanceador -> Nginx -> aplicación -> base de datos/API externa

Cada flecha puede tener su propio límite. Un CDN puede desistir antes que Nginx; Nginx puede desistir antes que la aplicación; la aplicación puede esperar una consulta sin timeout. Descubre quién generó la página de error a través de los encabezados y del panel del proveedor.

Paso 2: reproduce con identificación

curl -v --max-time 70 
  -H "X-Request-ID: diagnostico-504-001" 
  https://exemplo.com/relatorio

Prueba la misma ruta directamente en el origen solo en un entorno autorizado. Si el origen también tarda, el problema está en él o debajo de él. Si el origen es rápido, examina el proxy, DNS, conexión y capacidad intermedia.

Paso 3: correlaciona logs

Busca el ID de solicitud en todas las capas. Registra inicio, fin y duración de cada dependencia. Métricas útiles incluyen p50, p95 y p99, conexiones activas, saturación de CPU, memoria, cola, pool de la base de datos y consultas lentas.

Paso 4: trata base de datos y dependencias

Usa EXPLAIN (ANALYZE, BUFFERS) en una copia segura o consulta controlada. No ejecutes análisis destructivo en producción. Verifica filtros, índices, volumen retornado y N+1. Para servicios externos, define timeouts menores que el plazo total y reintentos solo en operaciones idempotentes, con espera creciente y aleatoriedad.

Paso 5: saca trabajos largos de la solicitud

Exportación, importación, procesamiento de imagen e informe extenso no necesitan mantener una conexión HTTP abierta. La API puede crear un trabajo, responder 202 Accepted, procesar en cola y disponibilizar el resultado después. Asegura idempotencia para evitar duplicación cuando el cliente repita.

Configuración Nginx con cautela

location /api/ {
  proxy_connect_timeout 5s;
  proxy_send_timeout 30s;
  proxy_read_timeout 30s;
  proxy_pass http://aplicacao;
}

Los valores son ejemplos, no recomendación universal. proxy_read_timeout mide el intervalo entre lecturas, no el tiempo total de la operación. Antes de aumentarlo, estima el impacto de conexiones atascadas y capacidad.

Cómo prevenir nuevos 504

• SLO por jornada crítica;
• timeout explícito en toda llamada externa;
• panel de latencia por ruta y dependencia;
• alerta antes de la saturación;
• prueba de carga con escenario realista;
• colas con límite, reintento y dead-letter;
• endpoint de salud que no dependa de todo;
• runbook con responsables y rollback.

Lee también error 502 en Nginx, error 500 en API y la guía de monitoreo de APIs.

Preguntas frecuentes

¿Reiniciar el servidor resuelve?

Puede liberar un recurso temporalmente, pero no explica la causa. Preserva métricas y logs antes de reiniciar cuando la operación lo permita.

¿Aumentar el timeout es seguro?

Solo cuando la duración es esperada y la capacidad ha sido calculada. De lo contrario, el sistema acumula trabajo y falla más tarde.

Fuentes primarias

• MDN: status 504 Gateway Timeout
• Nginx: proxy_read_timeout
• RFC 9110: status 504