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.
