Saltar al contenido

5xx · Errores del servidor

Error 504 Gateway Timeout: qué significa y cómo solucionarlo

El error 504 Gateway Timeout significa que el servidor intermedio (nginx, un balanceador, un CDN) esperó la respuesta de la aplicación de backend y se cansó de esperar. La aplicación está viva, pero tarda demasiado: una consulta lenta, una llamada externa colgada o un proceso pesado. En nginx el límite por defecto es de 60 segundos.

Qué significa el código 504

La diferencia con el 502 es importante para diagnosticar: en el 504 la conexión con el backend sí se ha establecido, pero la respuesta no ha llegado a tiempo. Subir el timeout lo tapa, pero lo correcto es averiguar por qué tarda tanto.

Las operaciones que tardan más de unos segundos (informes, exportaciones, importaciones) no deberían ejecutarse dentro de la petición HTTP. Lo correcto es encolarlas, responder 202 y avisar al terminar.

Causas habituales del error 504

  • Consultas lentas a la base de datos (sin índices, tablas bloqueadas).
  • Llamadas a APIs externas que no responden y no tienen timeout propio.
  • Procesos pesados ejecutados dentro de la petición (generación de PDF, informes).
  • Timeout del proxy más bajo que lo que tarda la operación.
  • Problemas de DNS o de red entre el proxy y el backend.

Cómo solucionar el error 504

  • Mide cuánto tarda el backend con curl -w "%{time_total}" directamente contra él.
  • Revisa el log de consultas lentas de la base de datos y añade índices.
  • Pon timeouts a todas las llamadas externas de tu código.
  • Mueve las tareas largas a una cola y responde 202.
  • Como solución temporal, sube proxy_read_timeout (o fastcgi_read_timeout con PHP).

Configuración y comandos

nginx: más margen para un endpoint concreto

nginx
location /api/informes/ {
    proxy_pass http://backend:8001;
    proxy_connect_timeout 10s;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
}

Medir el tiempo de respuesta

bash
curl -o /dev/null -s -w "conexión: %{time_connect}s  primer byte: %{time_starttransfer}s  total: %{time_total}s\n" http://127.0.0.1:8001/api/informes/anual

Ejemplo de respuesta

http
HTTP/1.1 504 Gateway Time-out
Server: nginx

# error.log:
# upstream timed out (110: Connection timed out) while reading response header from upstream

Herramientas para comprobarlo

Preguntas frecuentes

¿Qué significa 504 Gateway Timeout?

Que el proxy o CDN esperó demasiado la respuesta del servidor de la aplicación. El backend funciona, pero es demasiado lento para esa petición.

¿Basta con subir el timeout?

Lo tapa, pero el usuario sigue esperando y, si hay Cloudflare delante, este corta a los 100 segundos (error 524) por mucho que subas el de nginx. Lo correcto es acelerar la operación o hacerla en segundo plano.

Códigos relacionados

Ver todos los códigos de estado HTTP