504 Gateway Timeout: backends lentos, límites de espera y 502, 503 y 504 comparados
Un 504 Gateway Timeout significa que un proxy llegó hasta tu backend, esperó una respuesta y se rindió antes de que llegara. No se cayó nada ni nadie rechazó la petición: algo detrás del proxy es más lento de lo que el proxy está dispuesto a esperar.
Qué informa un 504
El RFC 9110 define el 504 para un servidor que actúa como pasarela o proxy y que no recibió a tiempo la respuesta de un servidor aguas arriba al que necesitaba acceder. Lo de "a tiempo" lo define la configuración, no la especificación, así que un 504 siempre habla de dos cosas a la vez: lo lento que fue el backend y qué límite tenía puesto el proxy.
Eso tiene una consecuencia práctica importante. Cuando un proxy devuelve un 504, el backend normalmente sigue trabajando en la petición. La conexión con el cliente ya no está, pero la consulta lenta sigue ejecutándose, el informe se sigue generando y los recursos siguen ocupados. Por eso una oleada de 504 suele empeorar un servidor: cada petición abandonada deja trabajo pendiente, y la cola crece más rápido de lo que se vacía.
504 frente a 502 frente a 503
| 502 Bad Gateway | 503 Service Unavailable | 504 Gateway Timeout | |
|---|---|---|---|
| Qué pasó | El backend dio una respuesta inválida o cerró la conexión | El servidor rechazó el trabajo a propósito | El backend aceptó el trabajo y nunca respondió a tiempo |
| Estado del backend | Caído, fallando o hablando el protocolo equivocado | En marcha, pero sobrecargado o en mantenimiento | En marcha y ocupado, todavía procesando |
| Velocidad de respuesta | Normalmente inmediata | Normalmente inmediata | Lenta, llega al alcanzar el límite de espera |
| Línea de registro típica | connect() failed o upstream prematurely closed connection | Regla de mantenimiento, o ningún upstream sano | upstream timed out (110: Connection timed out) |
Retry-After | Poco habitual | Habitual y recomendado | Poco habitual |
| Dónde mirar primero | ¿Está el proceso del backend en marcha? | Capacidad, indicadores de mantenimiento, comprobaciones de salud | Consultas lentas y dependencias lentas |
En la práctica, un 502 falla rápido, un 503 rechaza con educación y un 504 primero te hace esperar. La guía del 502 y el resumen de los 5xx tratan los otros dos al completo.
Por qué el backend es demasiado lento
- Consultas lentas a la base de datos. Un índice que falta, una consulta que creció con los datos, un patrón N+1 dentro de un bucle o contención de bloqueos con concurrencia. La causa más frecuente con diferencia.
- Llamadas lentas a terceros. Una petición saliente a una API sin su propio límite de espera hereda el peor día del servicio remoto y se lo pasa a tus visitantes.
- Arranques en frío. La primera petición tras un escalado, el arranque de un contenedor o un periodo de inactividad paga a la vez la inicialización, el establecimiento de conexiones y el calentamiento de cachés.
- Trabajo de verdad pesado en una petición web. Generar informes, exportaciones, procesar imágenes o importaciones masivas de forma síncrona acaba superando cualquier límite razonable.
- Contención de recursos. La CPU saturada, la presión de memoria y el uso de swap hacen que toda petición sea más lenta, así que las más lentas cruzan el límite las primeras.
- Límites de espera demasiado ajustados. Si un endpoint necesita legítimamente más tiempo del que permite el proxy, el error está en la configuración y no en el código.
- Problemas de red entre saltos. La pérdida de paquetes o los retrasos de resolución DNS de la dirección aguas arriba añaden una latencia que no aparece en los tiempos de la aplicación.
Cómo diagnosticar y solucionar un 504
- Mide el tiempo hasta el error. El retraso previo a un 504 suele coincidir con el límite configurado, lo que te dice qué salto lo produjo:
Un 504 a casi exactamente 60 segundos apunta a un límite de lectura por defecto del proxy. Uno a 30 o a 100 segundos apunta al componente que tenga ese número configurado, a menudo una CDN antes que tu propio proxy.curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://example.com/slow-page - Averigua si es un endpoint o todos. Una sola URL lenta es un problema de la aplicación. Todo lento a la vez es saturación de recursos o una dependencia que está fallando.
- Lee el registro de errores del proxy. Con nginx la línea es explícita:
Nombra el upstream y la fase, lo que separa una conexión lenta de una respuesta lenta.[error] upstream timed out (110: Connection timed out) while reading response header from upstream, upstream: "http://127.0.0.1:8080/" - Cronometra el backend directamente, sin el proxy. Si la misma petición tarda 90 segundos contra el origen, el proxy está diciendo la verdad y la solución corresponde a la aplicación.
- Perfila el camino lento. Mira el registro de consultas lentas y después las trazas de la aplicación. La mayoría de los 504 se reducen a una consulta o a una llamada saliente.
- Corrige la causa antes que el límite de espera. Añade el índice, guarda en caché el resultado caro, o mueve el trabajo realmente largo a una tarea en segundo plano que responda al momento e informe del progreso por separado.
- Sube el límite de espera solo cuando el trabajo sea legítimamente largo, y súbelo de forma coherente en todos los saltos. Un límite de 30 segundos en la CDN deja sin sentido un límite de 120 segundos en el origen.
- Pon límites de espera en tus propias llamadas salientes para que una dependencia lenta falle rápido con un error claro en lugar de consumir un proceso hasta que el proxy se rinda.
El tiempo de respuesta es el aviso temprano
Un 504 es el estado final de una ralentización que llevaba tiempo gestándose. Los tiempos de respuesta pasan de medio segundo a dos segundos y a diez, y nadie se da cuenta hasta que las peticiones empiezan a cruzar el límite. Una verificación HTTP programada registra el tiempo de respuesta de cada comprobación junto al código de estado, así que la tendencia se ve como una gráfica mucho antes del primer tiempo agotado, y la alerta llega en el primer fallo real y no cuando se llena la cola de soporte. Verificar desde varias regiones también ayuda, porque una ruta rápida desde un continente y lenta desde otro apunta al camino de red o a la configuración del borde, no a tu base de datos.