504 Gateway Timeout

Qué significa este error y cómo reconocerlo

• El navegador muestra 504 Gateway Timeout después de esperar, en lugar de fallar de inmediato.
• Los informes, las importaciones masivas, las exportaciones, el procesamiento de imágenes o las búsquedas complejas fallan, mientras las páginas simples siguen funcionando.
• Los fallos son más frecuentes cuando la aplicación está ocupada o las solicitudes están en cola.
• El backend responde cuando se prueba directamente, pero la misma solicitud agota el tiempo de espera a través de un proxy, CDN o load balancer.
• Los logs del gateway muestran que una solicitud upstream duró mucho tiempo antes de devolver el 504.
• La aplicación puede seguir procesando después de que el navegador haya recibido el timeout, lo que puede dejar trabajo duplicado o abandonado si se repite la acción.

Causas principales, ordenadas por probabilidad

1. Consultas de base de datos lentas o bloqueadas: La falta de índices, el crecimiento de las tablas, las consultas ineficientes y la contención de bloqueos pueden hacer que la aplicación espere más allá del límite del gateway.
2. Sobrecarga o colas en el backend: Las solicitudes pueden estar esperando workers de la aplicación, conexiones de base de datos, CPU, memoria u otros recursos limitados.
3. Una operación síncrona realmente larga: Las exportaciones, importaciones, informes o el procesamiento de archivos grandes pueden ser válidos, pero no adecuados para una solicitud de página normal.
4. Una API downstream o un webhook lentos: La aplicación puede estar esperando a otro servicio antes de poder responder.
5. Timeouts restrictivos del proxy o del servidor: Nginx, Apache, un CDN o un load balancer pueden dejar de esperar antes de que la aplicación termine.
6. Problemas de red entre capas del gateway: La latencia, la pérdida intermitente de paquetes o los fallos de enrutamiento son más plausibles en implementaciones con varios servidores o regiones, especialmente cuando el tiempo de la aplicación no explica el retraso.

Cómo solucionarlo

1. Identifica la solicitud que falla y su duración

Revisa los logs de acceso del gateway y de la aplicación para localizar la solicitud que produjo el 504. Registra la ruta o acción del usuario, la marca de tiempo, la duración de la respuesta, el estado y si fallan todas las solicitudes o solo una operación.

Si solo fallan los informes, las importaciones, las exportaciones o las búsquedas complejas, empieza por esa operación en lugar de tratar el incidente como una interrupción completa del servidor.

2. Compara el backend con la ruta completa de la solicitud

Con autorización y mediante una solicitud de prueba segura, compara el tiempo de respuesta directo del backend con el de la misma solicitud a través del proxy, CDN o load balancer.

• Una respuesta lenta tanto directamente como a través del gateway apunta a la aplicación, la base de datos, la capacidad o una dependencia.
• Una respuesta directa rápida, pero una solicitud proxy que falla, apunta a un timeout del intermediario, un problema de enrutamiento o un problema de red entre el gateway y el backend.

No evites los controles de acceso de producción ni envíes una solicitud que cambie el estado solo para realizar una prueba.

3. Investiga los tiempos de la base de datos y las esperas por bloqueos

Activa o inspecciona los diagnósticos de consultas lentas y esperas por bloqueos de la base de datos siguiendo las indicaciones operativas de la plataforma de base de datos. Busca consultas que se ejecuten cerca del timeout activo del gateway o lo superen.

Comprueba si faltan índices, si hay joins o filtros ineficientes, crecimiento de tablas y contención de bloqueos. Optimiza la consulta, reduce los datos procesados o añade un índice solo después de confirmar que aborda el cuello de botella medido. Coordina los cambios de esquema o de índices con el responsable de la base de datos, ya que pueden consumir recursos y afectar a las cargas de trabajo simultáneas.

No aumentes el timeout simplemente para ocultar una consulta que debería completarse rápidamente.

4. Comprueba la capacidad y las colas del backend

Revisa las métricas de la aplicación, el servidor web y el sistema para detectar agotamiento de workers, solicitudes en cola, límites de conexiones de base de datos, presión de CPU o memoria y otras restricciones de recursos durante el fallo.

Si las solicitudes esperan capacidad, aborda ese cuello de botella antes de ampliar los timeouts. Cambiar la capacidad o la configuración de los procesos puede afectar a la estabilidad del servicio, así que realiza esos cambios con la autorización operativa y el proceso de cambios aplicables.

5. Traslada el trabajo de larga duración a un background job

Para importaciones, exportaciones, generación de informes, procesamiento de correo electrónico y tareas similares, utiliza un background job cuando la aplicación lo admita. La solicitud inicial debe iniciar o poner el trabajo en cola, mientras una vista de estado independiente o una notificación informa del progreso y la finalización.

Esto evita mantener abierta durante toda la operación la conexión del navegador, el worker del gateway y la solicitud de la aplicación. Asegúrate de que el job tenga un manejo adecuado de reintentos y envíos duplicados antes de habilitar este patrón.

6. Revisa cuidadosamente la configuración de timeouts de Nginx

Si Nginx es el gateway, revisa las configuraciones aplicables de proxy_read_timeout y proxy_connect_timeout en el bloque server o location correspondiente. Confirma qué capa aplica el timeout antes de cambiar nada.

Aumenta un timeout solo cuando se espere que la operación tarde más, el backend esté saludable y el consumo adicional de conexiones y workers sea aceptable. Los cambios de configuración requieren la autorización adecuada. Después de guardar el cambio, valida la configuración y recarga Nginx según tu procedimiento habitual de despliegue; después, repite la operación que fallaba. No combines una recarga del servicio con diagnósticos de solo lectura en un cambio no planificado.

7. Revisa la configuración del proxy de Apache

En Apache con mod_proxy, revisa las configuraciones aplicables de Timeout y ProxyTimeout. Si hay cargas grandes involucradas, revisa también el comportamiento relevante de mod_reqtimeout.

Aplica, cuando sea posible, el cambio seguro más limitado para la ruta u operación afectada, con autorización y un plan de rollback. Repite la prueba usando la misma solicitud y confirma que las esperas más largas no estén agotando workers o conexiones.

8. Comprueba el comportamiento del CDN y del load balancer

Si el sitio utiliza Cloudflare u otro CDN o load balancer, revisa el timeout del gateway, el enrutamiento al origen, el estado y la configuración asociada al plan de ese servicio. Un intermediario puede aplicar un límite que no se pueda aumentar en la configuración disponible.

Cuando el origen necesite más tiempo que ese límite, optimiza la operación o trasládala a un procesamiento asíncrono en lugar de depender de una solicitud de navegador más larga.

9. Aísla las llamadas lentas a servicios de terceros

Mide por separado cada llamada a una API externa o webhook. Establece un timeout interno más corto para una dependencia cuando sea posible, gestiona el fallo explícitamente y devuelve un estado pendiente o que permita reintentar cuando el trabajo pueda finalizar más tarde.

Evita que una dependencia poco fiable consuma todo el timeout del gateway. Confirma que los reintentos estén limitados y sean seguros antes de añadir un comportamiento de reintento automático.

10. Verifica la solución

Repite exactamente la acción de página o la solicitud que fallaba. Confirma que se complete dentro del timeout activo del gateway y revisa después los logs para asegurarte de que el backend no esté acumulando trabajo abandonado, duplicado o con una duración inusualmente larga. Prueba a través de la ruta completa de producción, no solo directamente contra el backend.

Prevención y cómo verificar la solución

• Utiliza background jobs para importaciones, exportaciones, generación de informes, procesamiento de correo electrónico y otros trabajos que puedan superar la duración normal de una solicitud de página.
• Revisa los índices y los planes de consulta de las operaciones de base de datos que respaldan páginas con timeouts frecuentes a medida que crecen los datos.
• Supervisa por separado la duración de las solicitudes, el tiempo en cola, el tiempo de la base de datos, el uso de workers y el tiempo de las dependencias.
• Define deliberadamente los timeouts del proxy y de la aplicación para la operación legítima más lenta, manteniendo limitados los timeouts de las dependencias de terceros.
• Prueba las operaciones críticas a través de la ruta completa de producción, incluido el CDN o load balancer, en lugar de hacerlo solo contra el origen.
• Diseña de forma segura los reintentos y los envíos repetidos para que un timeout del gateway no cree jobs ni transacciones duplicados.
• Después de un cambio, repite exactamente la operación que agotó el tiempo de espera y confirma que se complete sin acumular trabajo excesivo en cola.

Preguntas frecuentes