El error 502 ocurre cuando un servidor que actúa como puerta de enlace (gateway) o proxy recibe una respuesta inválida o ninguna respuesta del servidor al que intenta conectarse.
En otras palabras:
El servidor intermedio dice:
“Intenté comunicarme con el servidor final, pero su respuesta fue incorrecta o inexistente.”
Este error es muy común en:
-
Nginx como reverse proxy
-
Cloudflare
-
Balanceadores de carga
-
APIs
-
Microservicios
-
Docker / contenedores
Causas más comunes
1. El servidor backend está caído o inaccesible
El proxy (Nginx, Cloudflare, Load Balancer…) no puede conectar con:
-
PHP-FPM
-
Node.js
-
Python
-
Servicio API
-
Base de datos externa
2. El backend tarda demasiado en responder
Si el servidor final supera el tiempo límite → 502.
3. Errores en la aplicación del backend
-
Código roto
-
Errores fatales
-
Bloqueos de procesos
-
Caída del servicio
4. Problemas con PHP-FPM
Muy común:
-
Pool saturado
-
Procesos congelados
-
Configuración incorrecta
5. Configuración incorrecta en Nginx/Apache
Ejemplos:
-
proxy_passmal configurado -
Rutas incorrectas
-
Puertos que no coinciden
-
Servicio escuchando en otro socket
6. Cloudflare no puede conectar con tu servidor
Causas comunes:
-
Firewall del hosting
-
IP bloqueada
-
Puerto no permitido
-
Servidor offline
7. Firewall o seguridad bloqueando la conexión
CSF, iptables o ModSecurity puede impedir comunicación entre servicios.
8. Errores en microservicios o Docker
-
Contenedor no levantado
-
Puerto mal expuesto
-
Servicio reiniciándose en loop
Soluciones recomendadas
1) Verificar que el backend está funcionando
Ejemplo en Linux:
Reiniciar si es necesario:
2) Probar conexión directa al backend
Ejemplo:
Si falla → el problema no es del proxy.
3) Revisar configuración de Nginx
Ejemplo típico:
Errores comunes:
-
Puerto incorrecto
-
Ruta equivocada
-
Backend apagado
4) Aumentar los timeouts
En Nginx:
5) Reiniciar servicios congelados
Especialmente PHP-FPM o Node.js.
6) Revisar logs de error del backend
Nginx:
Apache:
PHP-FPM:
7) Verificar reglas del firewall
Ejemplo:
-
CSF bloqueando puertos
-
Cloudflare bloqueado por hosting
-
IPs internas prohibidas
Asegurar que el proxy pueda conectarse con el backend.
8) Si usas Cloudflare: revisar estado DNS
Errores comunes:
-
Proxy naranja activado en puerto no soportado
-
Servidor caído
-
Puerto no permitido con proxy node
Solución rápida:
Cambiar a DNS only temporalmente.
Consejo Pro
El 502 casi siempre indica que tu servidor no se está comunicando bien internamente.
Checklist rápido:
¿El backend está activo?
¿El puerto es correcto?
¿El reverse proxy está bien configurado?
¿Hay errores en los logs?
¿Cloudflare está interfiriendo?
Resolver estos puntos suele eliminar el 502.
