Un error 504 Gateway Timeout significa que un servidor que actúa como gateway o proxy esperó la respuesta del servidor que tiene detrás y se cansó de esperar. La petición llegó a tu CDN, a tu balanceador de carga o a tu servidor web, se reenvió a la aplicación y la aplicación no respondió antes de que se agotara el tiempo límite.
Lo habitual es que el servidor que hay detrás del proxy siga funcionando. Simplemente es demasiado lento, o lo es algo de lo que depende. Por eso un 504 no se parece a la mayoría de las caídas: reiniciar rara vez lo arregla durante mucho tiempo. Esta guía te enseña a averiguar qué timeout saltó, qué suele hacer lenta la petición y cómo corregir la causa en lugar del síntoma.
Qué te dice un 504
Una petición a una web moderna atraviesa varias capas, y cada una tiene su propio límite de espera para la siguiente:
Una CDN como Cloudflare espera un tiempo fijo a tu servidor de origen.
Un balanceador de carga tiene un timeout de inactividad o de respuesta para cada destino.
nginx espera al upstream según proxy_read_timeout o fastcgi_read_timeout, 60 segundos por defecto.
La aplicación tiene sus propios límites, como max_execution_time de PHP o el timeout de los workers en Gunicorn.
El 504 lo devuelve la primera capa cuyo límite se agota. Sus vecinos significan otra cosa: un 502 Bad Gateway indica que el upstream respondió con algo no válido o no respondió en absoluto, y un 503 Service Unavailable indica que el servicio rechazó la petición porque está sobrecargado o en mantenimiento.
Averigua qué timeout saltó
Cronometra la petición. Un 504 que siempre llega tras el mismo número de segundos apunta a un límite concreto:
curl -s -o /dev/null -w «status %{http_code} after %{time_total}s\n» https://www.example.com/reports
status 504 after 60.04s
Después revisa las cabeceras de la respuesta y la página de error para ver qué capa respondió, como con cualquier error 5xx. Una página sencilla de nginx con server: nginx significa que el timeout saltó en tu propio servidor web. Una página con la marca de la CDN que menciona tu host significa que la CDN se cansó de esperar a tu servidor de origen.
nginx registra el timeout junto con la dirección a la que estaba esperando:
upstream timed out (110: Connection timed out) while reading response header from upstream,
upstream: «fastcgi://unix:/run/php/php8.3-fpm.sock», request: «GET /reports HTTP/2.0»
Ya sabes qué página es lenta y qué parte del stack la tuvo esperando. El siguiente paso es descubrir por qué.
Causas habituales y cómo solucionarlas
Consultas lentas a la base de datos
Es el motivo más frecuente. Una consulta que tardaba 50 milisegundos con mil filas tarda 40 segundos con un millón, porque recorre la tabla entera. Activa el registro de consultas lentas y busca las consultas de esa página:
# MySQL / MariaDB
SET GLOBAL slow_query_log = ‘ON’;
SET GLOBAL long_query_time = 1;
# PostgreSQL, in postgresql.conf
log_min_duration_statement = 1000
Ejecuta la consulta más lenta con EXPLAIN y busca recorridos completos de tabla. Lo normal es que falte un índice. El otro sospechoso habitual son los bloqueos: una transacción larga o una migración pueden retener una tabla mientras esperan todas las peticiones que la necesitan.
API externas lentas
Muchas páginas llaman a otros servicios mientras se generan: una pasarela de pago, una calculadora de envíos, un buscador, un CRM. Si ese servicio va lento, tu página va lenta y tu proxy agota el tiempo de espera. Pon un timeout corto en cada llamada saliente, de unos pocos segundos en lugar del valor por defecto de la librería, y decide qué muestra la página cuando la llamada falla. Un coste de envío que dice «se calcula al finalizar la compra» es mejor que un 504.
No pierdas de vista los servicios de los que dependes. La monitorización de terceros de Uptimecheck sigue las páginas de estado de 31 servicios como Klarna, Shopify y Cloudflare, así que un proveedor lento aparece junto a tus propias comprobaciones.
Pocos workers para el tráfico que hay
Cuando todos los workers están ocupados, las nuevas peticiones esperan en cola. No son lentas en sí, solo esperan su turno, y mientras tanto el reloj del proxy sigue corriendo. PHP-FPM lo deja claro en su log con server reached pm.max_children. Añadir workers solo ayuda si el servidor tiene memoria y CPU para ellos. A menudo es mejor acortar cada petición, para que los mismos workers atiendan más, y cachear las páginas que no cambian según el visitante.
Tareas largas dentro de una petición web
Las exportaciones, las importaciones, la generación de informes, el procesamiento de imágenes y el envío de cientos de emails no deben ir dentro de una petición web. Tardan lo que tardan y, tarde o temprano, alguna supera un timeout. Pásalas a una cola en segundo plano: la petición lanza la tarea y responde al instante, y la página consulta el resultado o el usuario recibe un email cuando termina.
El propio servidor está sobrecargado
Una CPU al límite, una presión de memoria que lleva al servidor a usar swap o un disco que no da abasto ralentizan todo a la vez. Si ves un 504 en todas las páginas y no solo en una, el problema está aquí. Revisa CPU, memoria, swap y espera de disco en ese mismo periodo:
uptime
free -m
iostat -x 5 3
La monitorización de servidores guarda ese historial, así que puedes ver qué hacía el servidor en el minuto exacto en que empezaron los 504 en lugar de hacer suposiciones a posteriori.
Problemas de red entre las capas
Si el proxy no llega a conectar con el upstream, por ejemplo porque un firewall descarta los paquetes en lugar de rechazarlos, la conexión se queda colgada hasta que agota el tiempo. Eso acaba en un 504 y no en un 502. Comprueba desde la misma máquina que el proxy puede abrir una conexión con la dirección y el puerto del upstream.
Cuándo sí conviene subir el timeout
A veces una petición es larga con razón: una subida grande, un informe que un administrador pide una vez al mes. En ese caso, sube el límite solo para esa ruta y mantén el orden de las capas, de modo que las exteriores esperen más que las interiores:
location /admin/exports/ {
proxy_read_timeout 300s;
proxy_pass http://app;
}
Subir el límite en todo el sitio no arregla las páginas lentas. Solo hace que los visitantes esperen más antes de ver un error, y deja que las peticiones lentas ocupen workers durante más tiempo, lo que alarga la cola para todos los demás.
Cómo detecta la monitorización los 504
Un 504 rara vez aparece de la nada. La página se volvió un poco más lenta cada semana a medida que crecían los datos, hasta que un día superó el límite. Y eso es una buena noticia, porque significa que puedes verlo venir.
Vigila el tiempo de respuesta, no solo el código de estado. Uptimecheck registra el tiempo de respuesta de cada comprobación, desglosado en DNS, conexión, TLS, servidor y descarga, para que veas si el más lento es el servidor o la red. Una alerta de respuesta lenta te avisa cuando una página supera el límite que hayas fijado, mucho antes de que salte el timeout del proxy. Nuestra guía sobre qué es un buen tiempo de respuesta te ayuda a elegir ese límite.
Confirma los fallos antes de avisar. Las comprobaciones se ejecutan hasta cada minuto desde Estocolmo, Londres y Nueva York, y cada fallo se confirma desde una segunda ubicación, así que una sola petición lenta no despierta a nadie.
Monitoriza directamente las páginas lentas. La búsqueda, el checkout, las páginas de cuenta y los informes son donde se producen los 504, y casi nunca en la página de inicio. Añade monitores de uptime para ellas, con un timeout acorde a lo que un visitante está dispuesto a esperar.
Checklist para el error 504
Cronometra la petición: una cifra redonda de segundos te dice qué límite saltó.
Lee las cabeceras y la página de error para ver qué capa agotó el tiempo.
Localiza la página lenta en el log de errores del proxy.
Busca consultas lentas, bloqueos y llamadas externas lentas en esa página.
Revisa workers, CPU, memoria, swap y disco en esos mismos minutos.
Corrige la parte lenta, cachéala o pásala a una tarea en segundo plano.
Sube los timeouts solo en las rutas que son largas con razón, con las capas exteriores esperando más que las interiores.
Configura alertas de respuesta lenta para ver el próximo 504 cuando todavía es solo una ralentización.