El error 504 Gateway Timeout es un código de estado HTTP que indica que un servidor actuando como puerta de enlace (gateway) o proxy no recibió una respuesta a tiempo de otro servidor superior (backend o servidor de aplicaciones) para completar la solicitud HTTP.
En entornos empresariales, este fallo aparece habitualmente al ejecutar consultas pesadas en bases de datos, procesar informes mensuales en un software ERP/CRM o importar un gran volumen de datos mediante APIs.
A continuación, detallamos la guía paso a paso para diagnosticar el cuello de botella y solucionar este tiempo de espera agotado tanto en Nginx como en Apache.
Causas principales del error 504 Gateway Timeout
Antes de ajustar los parámetros de red o servidor, es importante identificar dónde se produce el retraso de la petición:
- Sobrecarga de la base de datos: Consultas SQL lentas o sin índices que bloquean el proceso principal durante más tiempo del límite permitido.
- Tiempo de ejecución de PHP insuficiente: El parámetro
max_execution_timede PHP finaliza el script antes de que la aplicación devuelva la respuesta. - Límites de proxy en Nginx o Apache: Los valores por defecto de tiempo de espera (timeout) en el servidor web son demasiado reducidos para operaciones masivas B2B.
- Bloqueos en el Firewall o CDN: Cortafuegos de red o plataformas como Cloudflare interrumpen la conexión si el servidor de origen tarda más de 30 o 60 segundos en responder.
Solución 1: Aumentar los tiempos de espera en Nginx (proxy_read_timeout)
Si utilizas Nginx como proxy inverso por delante de un servidor de aplicaciones (como PHP-FPM o Node.js), debes ampliar el margen de tiempo en su archivo de configuración (nginx.conf o el bloque de tu sitio en /etc/nginx/sites-available/).
- Abre el archivo de configuración del sitio mediante la consola:
sudo nano /etc/nginx/sites-available/tudominio.conf - Dentro del bloque
location /, añade o modifica las siguientes directivas:
location / {
proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;
send_timeout 300;
}
- Guardas los cambios, verifica la sintaxis del archivo ejecutando
sudo nginx -ty reinicia el servicio:sudo systemctl restart nginx
Solución 2: Ajustar el tiempo de espera en servidores Apache (TimeOut)
En servidores basados en Apache, la directiva TimeOut define cuántos segundos esperará el servidor para recibir las peticiones antes de abortar la conexión.
- Abre el archivo de configuración principal de Apache (habitualmente en
/etc/apache2/apache2.confo/etc/httpd/conf/httpd.conf). - Localiza la directiva TimeOut y aumenta su valor (por defecto suele estar en 60 segundos):
# Aumentar tiempo de espera a 300 segundos (5 minutos)
TimeOut 300
Si utilizas el módulo mod_proxy o ProxyPass para comunicar con un backend, ajusta también el parámetro dentro de la declaración del proxy:
ProxyPass / http://127.0.0.1:8080/ timeout=300
- Reinicia el servidor web ejecutando
sudo systemctl restart apache2ohttpd.
Solución 3: Ampliar los límites de ejecución en PHP (max_execution_time)
De nada sirve aumentar el tiempo de espera en el servidor web si la capa de aplicación en PHP detiene el proceso de forma prematura.
Parámetro en php.ini | Valor por Defecto | Valor Recomendado para Procesos Pesados |
|---|---|---|
max_execution_time | 30 segundos | 300 (5 minutos) |
max_input_time | 60 segundos | 300 |
memory_limit | 128M | 512M o superior |
Pasos para aplicar el cambio:
- Localiza y edita el archivo
php.inide tu servidor. - Modifica la línea
max_execution_time = 30pormax_execution_time = 300. - Si utilizas PHP-FPM, abre el archivo de configuración del grupo (
www.conf) y añade o ajusta:request_terminate_timeout = 300s - Reinicia el servicio PHP-FPM (
sudo systemctl restart php8.x-fpm).
Preguntas Frecuentes (FAQ)
¿Cómo influye Cloudflare u otros servicios CDN en este error?
Cloudflare establece un límite duro de tiempo de espera HTTP de 100 segundos para las cuentas gratuitas y Pro. Si tu backend tarda más de 100 segundos en responder, Cloudflare devolverá una pantalla de error 504 propia, independientemente de la configuración de tu servidor.
¿Aumentar el timeout soluciona la causa raíz del problema?
No. Aumentar el tiempo de espera es un parche para permitir que los procesos largos se completen, pero la solución técnica definitiva pasa por optimizar las consultas a la base de datos, implementar índices o ejecutar las tareas pesadas en segundo plano mediante colas de trabajo (background workers).