HTTP 504 Gateway Timeout
El intermediario se cansó de esperar: el servidor de origen no respondió dentro del límite de tiempo del proxy.
Qué significa HTTP 504
HTTP 504 Gateway Timeout lo emite un proxy, balanceador de carga o CDN cuya solicitud al servidor de origen no recibió respuesta dentro de su tiempo límite. A diferencia de 502 — donde el origen respondió mal — con 504 no respondió en absoluto a tiempo.
La causa raíz es casi siempre algo lento entre bastidores: una consulta de base de datos costosa, una API externa que no responde, o un pool de hilos de la aplicación agotado por la carga.
Causas comunes de los errores 504
- Una consulta de base de datos lenta o un índice faltante que hace que un endpoint tarde más de lo que el proxy permite.
- La aplicación esperando a una API externa que en sí misma es lenta o está caída.
- Backend saturado: todos los workers ocupados, solicitudes en cola más allá del tiempo límite.
- Problemas de red entre el proxy y el origen (enrutamiento, pérdida de paquetes, DNS).
- Desajuste de tiempo de espera: la aplicación legítimamente necesita 60s, el proxy corta a los 30s.
Cómo solucionarlo como visitante
- Reintenta después de un momento — un único 504 a menudo es una solicitud lenta, no una interrupción.
- Para una acción que enviaste (pago, pedido), comprueba si realmente se procesó antes de reintentar.
Cómo solucionarlo como desarrollador
- Encuentra el endpoint lento en los registros de acceso/APM: arregla la consulta, añade índices, cachea el resultado.
- Mueve el trabajo lento a tareas en segundo plano y responde rápidamente con un estado que el cliente pueda sondear.
- Alinea los presupuestos de tiempo de espera de extremo a extremo (app < proxy < CDN) para que el eslabón más lento sea conocido e intencional.
- Añade circuit breakers alrededor de APIs externas inestables en lugar de dejar que bloqueen tus workers.
Ejemplo de respuesta
HTTP/1.1 504 Gateway Timeout Server: nginx Content-Type: text/html <html><body><h1>504 Gateway Timeout</h1></body></html>
Preguntas frecuentes
¿Cuál es la diferencia entre 504 y 502?
504 significa que el origen nunca respondió dentro del tiempo límite; 502 significa que respondió con algo inválido.
¿Es un 504 un problema de la conexión del usuario?
No — está entre el proxy del sitio y su backend. La red del usuario está bien.
¿Se procesó mi solicitud enviada si obtuve un 504?
Posiblemente sí — el tiempo de espera afectó a la respuesta, no necesariamente al procesamiento. Comprueba el estado antes de reintentar ciegamente acciones no idempotentes.