⏳ Error 504 – Tiempo de espera agotado (Gateway Timeout)

El error 504 ocurre cuando un servidor que actúa como puerta de enlace (gateway) o proxy no recibe una respuesta a tiempo del servidor principal (backend).

En otras palabras:
“El servidor al que intento conectarme no responde. Me cansé de esperar.”

Se parece al 502, pero con una diferencia clave:

502 = Respuesta inválida del backend
504 = El backend NO respondió a tiempo

Muy común en:

Nginx
Cloudflare
Balanceadores de carga
APIs lentas
Microservicios
Servidores saturados

✅ Causas más comunes

🐢 1. El backend está demasiado lento

La causa más típica. El servidor final tarda tanto que el proxy “se rinde”.

🔁 2. Timeouts demasiado bajos en Nginx, Apache o Cloudflare

El servidor corta la conexión antes de que el backend termine su trabajo.

💾 3. Consultas a la base de datos extremadamente lentas

Ejemplos:

SELECT sin índices
Tablas muy grandes
JOINs complejos
Bloqueos de escritura → deadlocks

🔧 4. Código backend que tarda más de lo permitido

Loops pesados
Procesos mal optimizados
Procesos que consumen CPU
Cálculos complejos o archivos grandes

☁️ 5. Cloudflare no puede conectar con el servidor origen

Cloudflare devuelve 504 si no recibe respuesta rápida del hosting.

🔒 6. Firewall bloqueando la conexión

CSF, iptables o firewalls externos pueden impedir que el proxy hable con el backend.

🧱 7. Microservicios o APIs apagadas

Un servicio A intenta hablar con servicio B, pero B está:

Caído
Colgado
Lento
Saturado

🔧 Soluciones recomendadas

1️⃣ Aumentar los timeouts en Nginx

Editar configuración:

Reiniciar después:

2️⃣ Optimizar consultas a la base de datos

Crear índices
Optimizar JOINs
Revisar logs de consultas lentas
Resolver locks o deadlocks

En MySQL:

3️⃣ Optimizar el código backend

Evitar:

Procesos demasiado largos
Búsquedas pesadas
Loops innecesarios
Generación de archivos enormes en caliente

4️⃣ Revisar estado de PHP-FPM, Node.js, Python, etc.

Ejemplo:

Si el backend está congelado, habrá 504.

5️⃣ Verificar firewall o reglas de seguridad

Asegura que Nginx o Cloudflare puedan comunicarse con el backend.

6️⃣ Aumentar timeout en Cloudflare

Cloudflare permite ~100 segundos máximo.
Si tu backend tarda más → Cloudflare cortará.

Soluciones:

Optimizar backend
Saltarse Cloudflare (modo DNS Only)
Usar workers o colas

7️⃣ Usar colas de procesamiento

Si la operación tarda demasiado:

Jobs en segundo plano
Mensajería: Redis, RabbitMQ
Procesos asíncronos

Evita bloquear al usuario.

8️⃣ Verificar logs

Nginx:

Apache:

Backend (PHP/Node):

Los logs revelan si hubo bloqueo, lentitud o caída.

🔐 Consejo Pro

El error 504 casi siempre indica que tu aplicación está:

Lenta
Saturada
Con cuellos de botella
O mal configurada

Implementa siempre:

Monitoreo
Logs
Alertas
Timeouts correctos
Optimización de base de datos

Para evitar este error en producción.