Loading...

Errores HTTP

504 Gateway Timeout: quién esperó, cuánto tiempo y cómo solucionarlo

Un 504 es un problema de espera, no una conexión rota. Un proxy situado delante de su sitio pidió una página a su servidor, esperó todo lo que se le permitía y se rindió. Esta guía le muestra cómo averiguar quién esperaba a quién, qué tiempo de espera se agotó primero y cómo arreglar la parte lenta en lugar de ocultarla.

9 min de lectura Intermedio Actualizado

504 Gateway Timeout: quién esperó, cuánto tiempo y cómo solucionarlo

Qué dice realmente un 504

Un gateway es cualquier elemento que recibe una solicitud y la reenvía: un edge de CDN, un balanceador de carga, nginx delante de PHP-FPM o de Node. 504 Gateway Timeout es el gateway diciendo: llegué al servidor que tengo detrás, le pregunté y la respuesta no llegó antes de mi límite.

Eso distingue al 504 de sus vecinos. Un 502 Bad Gateway significa que la respuesta era inservible o que la conexión falló. Un 503 Service Unavailable significa que algo rechazó la solicitud a propósito. Un 504 significa que nadie rechazó nada: la solicitud se aceptó y es muy posible que siga ejecutándose en su servidor cuando al visitante ya se le ha mostrado el error.

Este último punto importa en la práctica. Un 504 no cancela el trabajo: un informe que agotó el tiempo en el proxy puede terminar en el origen un minuto después, y un visitante que vuelve a pulsar el botón inicia una segunda copia.

Quién esperó a quién

Una solicitud típica pasa por varios puntos de espera: visitante → edge del CDN → su servidor web (nginx o Apache) → su aplicación (PHP-FPM, Node, un contenedor) → su base de datos o una API externa. Cada flecha es un gateway con su propio timeout, y se configuran de forma independiente, a menudo por personas distintas.

La regla que más tiempo ahorra: el timeout más corto de la cadena es el que salta. Si el edge espera 60 segundos, su nginx espera 60 segundos a PHP-FPM y PHP detiene un script a los 30, la solicitud nunca se acerca al límite del edge: PHP la termina a los 30 segundos y el salto superior informa del fallo.

Por eso la primera pregunta no es «por qué el CDN agota el tiempo», sino ¿cuánto tardó en aparecer el error? Un 504 a casi exactamente 60 segundos apunta a un límite de 60 segundos; uno a 30 segundos, a un límite de 30. Compare esa cifra con los límites que conoce y el salto que se rindió suele delatarse solo.

Las causas detrás de casi todos los 504

Una consulta lenta. Una consulta sin el índice adecuado, que recorre una tabla que pasó de diez mil filas a diez millones. Era rápida en el lanzamiento y hoy es lenta, y no cambió nada en el código.

Trabajo largo por naturaleza. Exportaciones a CSV y Excel, informes en PDF, importaciones masivas, procesamiento de imágenes o vídeo, una copia de seguridad iniciada desde una página de administración. No son errores; son tareas que no deberían ejecutarse dentro de una solicitud web.

Una llamada externa sin timeout. Un proveedor de pagos, una API de envíos, un servicio de búsqueda. Cuando se queda colgado, su solicitud se cuelga con él, y sus visitantes esperan a que termine la caída de otro.

Un origen sobrecargado. Cuando todos los workers o hilos de PHP-FPM están ocupados, las solicitudes nuevas esperan en una cola antes incluso de empezar. Cada solicitud puede ser rápida; es la espera en la fila lo que agota el tiempo. Estos 504 se concentran en los picos de tráfico.

Problemas de red entre saltos. Un firewall que descarta paquetes en silencio en lugar de rechazarlos hace que el proxy espere una conexión que nunca se abrirá. El resultado es un 504 en lugar de un fallo rápido.

Diagnóstico: mida dónde se va el tiempo

Mida la solicitud a través del CDN y después la misma solicitud directa a su origen. curl puede dividir el tiempo en fases, como en los comandos de abajo.

Si connect es grande o nunca termina, el problema es llegar al origen: un firewall, el enrutamiento, un servidor caído. Si connect es rápido y ttfb (tiempo hasta el primer byte) es largo, el origen aceptó la solicitud y sigue trabajando en ella: es el 504 clásico, y la respuesta está en su aplicación.

El segundo comando evita el CDN con --resolve y sigue enviando su nombre de host. Si el origen por sí solo también tarda 70 segundos, el edge dice la verdad. Si responde en dos segundos directamente pero agota el tiempo a través del CDN, busque qué es distinto: una regla de firewall, otro backend para ese nombre de host o cabeceras que su aplicación trata de otra forma.

Después lea los logs del propio origen de ese momento. En nginx, añada $request_time y $upstream_response_time al formato del log; en Apache, %D. Active el log de consultas lentas de su base de datos y, para PHP, el slowlog de PHP-FPM, que escribe un stack trace de cada solicitud que tarda demasiado: normalmente el camino más rápido hasta la línea exacta.

Medir una solicitud a través del CDN y directamente al origen

# through the CDN
curl -o /dev/null -s -w 'connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  https://www.example.com/reports/export

# straight to the origin, same hostname
curl -o /dev/null -s -w 'connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  --resolve www.example.com:443:ORIGIN_IP https://www.example.com/reports/export

Arregle primero la parte lenta

Aumentar un timeout hace desaparecer el error y deja al visitante esperando exactamente lo mismo. Antes de tocar cualquier límite, haga la solicitud más corta.

Índices y caché. Encuentre la consulta lenta en el slow log y añada el índice que necesita. Almacene en caché los resultados que comparten muchos visitantes, en la aplicación o en el edge con cabeceras Cache-Control.

Saque el trabajo largo de la solicitud. Convierta una exportación en una tarea en segundo plano: el clic pone la tarea en cola y responde de inmediato, la página muestra el progreso y el archivo terminado llega como enlace de descarga o por correo. La solicitud web sigue siendo corta por grande que sea la tarea.

Dé a cada llamada externa su propio timeout. Unos pocos segundos, con una alternativa razonable, para que la caída de otra empresa no se convierta en la suya.

Dimensione el origen para el pico. Si los 504 se concentran en las horas de más tráfico, añada workers (pm.max_children de PHP-FPM, procesos de Node, réplicas de contenedor) y deje que la caché del edge absorba las solicitudes repetidas para que menos de ellas lleguen al origen.

Aumente el timeout solo donde corresponde

Algunas solicitudes son largas por diseño: una subida grande que se está procesando, un informe que no se puede dividir, una API que transmite resultados en streaming. Para esas, aumente el límite, solo para esa ruta y en todos los saltos.

En cdn.com.tr es un ajuste de la regla de entrega: Tiempo de espera de respuesta del origen (segundos), de 1 a 3.600 segundos por regla, 60 segundos por defecto. Cree una regla aparte para la ruta que lo necesite, por ejemplo /admin/export/, y dé solo a esa regla un timeout más largo. El resto del sitio conserva el valor corto por defecto y sigue fallando rápido cuando algo va realmente mal. En el dominio de una aplicación de Managed Container el valor por defecto es de 300 segundos, salvo que la regla establezca otro.

El timeout cuenta el tiempo entre dos fragmentos de datos de su origen, no la duración total de la solicitud. Mientras los datos sigan fluyendo, el edge mantiene la solicitud abierta. Por eso una respuesta en streaming —un CSV escrito fila a fila, un feed de progreso— puede durar muchos minutos, mientras que un script que calcula durante cinco minutos y luego lo imprime todo de una vez no puede.

Después alinee los saltos que hay detrás del edge: proxy_read_timeout o fastcgi_read_timeout de nginx, max_execution_time de PHP, el límite propio de su servidor de aplicaciones. Una ruta larga solo es tan larga como su límite más corto.

Cuando hay un CDN delante

Un CDN cambia lo que le cuesta un 504.

Las páginas en caché siguen sirviéndose. En una regla que almacena en caché, si su origen agota el tiempo mientras el edge conserva una copia de la página, incluso caducada, el edge sirve esa copia en lugar del error. Un minuto lento en el origen se convierte en una página algo desactualizada en vez de una página rota. Es un buen motivo para almacenar en caché todo lo que se pueda, con TTL acordes a la frecuencia real con que cambia el contenido.

Las rutas lentas se hacen visibles. Cuando los 504 aparecen solo en /search o /checkout, las rutas dinámicas y sin caché, sabe exactamente dónde buscar.

Las conexiones de larga duración siguen la misma regla. Una conexión WebSocket que no envía nada durante más tiempo que el timeout se cierra. Dé a la ruta de WebSocket una regla aparte con Permitir conexiones WebSocket activado y un timeout adecuado, o envíe un pequeño mensaje de latido con más frecuencia que el límite. La guía de conexión con el origen muestra ambos ajustes.

Cómo configurarlo

Guías paso a paso en el centro de ayuda:

Preguntas frecuentes sobre 504 Gateway Timeout

¿Un 504 es culpa de mi servidor o del CDN?

En la mayoría de los casos el tiempo se gasta en su origen y el edge es quien esperó. Compare una solicitud a través del CDN con una solicitud directa al origen. Si el origen por sí solo es igual de lento, la solución está en el origen; si es rápido directamente y lento solo a través del CDN, busque una diferencia de firewall o de enrutamiento que afecte a la conexión del edge.

¿Cuál es el timeout de origen por defecto en cdn.com.tr?

60 segundos sin datos de su origen. Puede configurarlo por regla de entrega, de 1 a 3.600 segundos, en Tiempo de espera de respuesta del origen (segundos). En el dominio de una aplicación de Managed Container el valor por defecto es de 300 segundos.

¿Debo poner el timeout en 3.600 segundos en todas partes?

No. Un timeout largo en todas las rutas significa que, cuando algo se rompe de verdad, los visitantes miran un indicador de carga durante una hora en lugar de recibir una respuesta en un minuto, y las solicitudes atascadas se acumulan en su origen. Conserve el valor por defecto para el sitio y aumente solo en la regla de la ruta que es lenta por diseño.

¿Por qué mi exportación funciona con archivos pequeños y falla con los grandes?

Porque construye el archivo completo antes de enviar el primer byte. Las exportaciones pequeñas terminan dentro del límite; las grandes, no. Envíe el archivo en streaming a medida que se genera, o ejecute la exportación como tarea en segundo plano y envíe un enlace de descarga cuando esté lista.

¿Puede aparecer un 504 aunque mi aplicación sea rápida?

Sí, cuando las solicitudes hacen cola antes de empezar. Si todos los workers están ocupados, una solicitud rápida puede esperar lo suficiente como para agotar el tiempo. Los 504 que aparecen solo en horas de mucho tráfico apuntan a la capacidad, no al código.

¿Ayuda actualizar la página?

A veces, pero cada actualización inicia de nuevo el mismo trabajo lento en su origen. En páginas pesadas, las actualizaciones repetidas añaden carga justo cuando el servidor ya está al límite.