Error 502 Bad Gateway: qué significa, causas y cómo solucionarlo

La aplicación o PHP-FPM no responde

• Qué comprobar: Consulta el servicio directamente desde el servidor donde funciona el proxy.
• Qué hacer: Restaura el proceso y revisa los logs para determinar por qué se detuvo.

Host, puerto o socket incorrecto

• Qué comprobar: Compara la configuración del proxy con el puerto o socket donde escucha la aplicación.
• Qué hacer: Corrige el destino del upstream y valida la configuración antes de recargar el proxy.

Sobrecarga o conexiones reiniciadas

• Qué comprobar: Revisa el consumo de recursos y los logs del proxy y de la aplicación.
• Qué hacer: Elimina el cuello de botella o recupera la capacidad necesaria.

Falla de DNS, red, firewall o TLS

• Qué comprobar: Prueba la resolución DNS y la conectividad desde el gateway.
• Qué hacer: Corrige el registro DNS, la ruta de red, la regla del firewall o la configuración del certificado.

Respuesta no válida del upstream

• Qué comprobar: Busca en los logs del gateway el motivo exacto por el que rechazó la respuesta.
• Qué hacer: Corrige los encabezados o la salida generada por la aplicación.

Antes de cambiar configuraciones, conserva la URL, hora con zona horaria, código HTTP y logs relacionados.

¿Qué significa 502 Bad Gateway?

El RFC 9110 define el código 502 como la respuesta de un gateway o proxy que recibió una respuesta no válida de un servidor entrante. El navegador suele haber llegado al intermediario; el fallo ocurre entre componentes del servidor.

Una solicitud puede seguir esta ruta:

Navegador → CDN o balanceador → proxy inverso → aplicación

El componente que muestra el error no siempre lo causó. NGINX podría devolver 502 porque la aplicación dejó de escuchar o el proxy apunta al puerto equivocado. Upstream es el servidor al que el proxy reenvía la solicitud.

Diferencia entre los errores 500, 502, 503 y 504

Error 500 Internal Server Error

El servidor encontró una condición inesperada mientras procesaba la solicitud. El fallo ocurre dentro del servidor encargado de responder.

Error 502 Bad Gateway

Un gateway o proxy recibió una respuesta no válida de un servidor upstream. El fallo ocurre en la comunicación entre dos capas del servidor.

Error 503 Service Unavailable

El servicio no puede procesar la solicitud temporalmente. Normalmente se relaciona con sobrecarga, mantenimiento o falta de capacidad.

Error 504 Gateway Timeout

El gateway no recibió a tiempo la respuesta del servidor upstream. La diferencia principal es que se agotó el tiempo de espera.

Un upstream lento o interrumpido puede producir códigos diferentes dependiendo del intermediario. Por eso, no debes asumir que todos los timeouts aparecerán como un error 502.

Un upstream lento puede producir códigos distintos según el intermediario; no todo timeout es un 502. Si el propio servidor devuelve 500, consulta la guía para solucionar un error 500 Internal Server Error.

Qué hacer si eres visitante del sitio

Un visitante no puede reparar el servidor de origen, pero sí comprobar si el error depende de su red o dispositivo:

1. Espera unos segundos y recarga la página una vez.
2. Abre el sitio en una ventana privada o en otro navegador.
3. Prueba otra red y desconecta temporalmente una VPN o proxy personalizado.
4. Consulta la página oficial de estado del servicio, si existe.
5. Si el error continúa en distintos dispositivos o redes, informa al propietario e incluye la URL y la hora.

Según MDN, la mayoría de las causas requieren al propietario o administrador; las excepciones pueden estar en la red, firewall, proxy, VPN o DNS local. Borrar la caché no repara una falla entre servidores.

Cómo diagnosticar un error 502 si administras el sitio

1. Registra el fallo antes de hacer cambios

Anota URL, hora y zona horaria, código, despliegues recientes e identificador de solicitud o traza. Conserva los encabezados públicos con:

Correlaciona esa hora en los logs de CDN, proxy, aplicación, PHP-FPM y sistema. Connection refused, connection reset, cierre anticipado o encabezado no válido señalan causas distintas.

2. Separa el gateway público del servidor de origen

Prueba la URL pública y después, desde un sistema autorizado, el origen. Si solo falla la primera, revisa CDN, balanceador, proxy, TLS o red. Si ambas fallan, investiga la aplicación y el origen.

Con Cloudflare, compara la respuesta pública con los logs del origen. Su guía de errores 502 y 504 recomienda identificar quién emitió el error antes de corregirlo. No expongas un origen privado para probar.

Causas del error 502 y cómo solucionarlas

La aplicación, el contenedor o PHP-FPM está detenido

Confirma que el proceso escucha en el puerto o socket esperado y consulta su endpoint de salud desde el proxy. Si está detenido, restáuralo y revisa logs de fallos, memoria, despliegues y dependencias.

En PHP, consulta la configuración oficial de PHP-FPM para revisar workers, slow log y límites de ejecución.

El proxy inverso apunta al destino equivocado

Un despliegue puede cambiar hostname, puerto, contenedor o socket mientras el proxy conserva el valor anterior. Compáralo con proxy_pass, corrige la discrepancia y valida antes de recargar.

La documentación del proxy de NGINX define las directivas de upstream y timeout. Consúltala antes de copiar valores de otro entorno.

El origen está sobrecargado o cierra conexiones

Revisa CPU, memoria, workers, latencia de base de datos, colas y conexiones. Un reset puede indicar un proceso caído, un destino que cerró la solicitud o conexiones persistentes incompatibles.

AWS documenta respuestas mal formadas, encabezados no válidos, cierres y fallos TLS upstream en su guía de Application Load Balancer.

Aumenta el timeout solo si mediste que la operación necesita más tiempo; hacerlo a ciegas puede ocultar una consulta lenta, un worker bloqueado o una dependencia caída.

DNS, firewall, red o TLS bloquea el upstream

Resuelve el hostname desde el gateway. Confirma que firewall, rutas y políticas permiten el puerto correcto. Para upstream HTTPS, verifica nombre del certificado, cadena de confianza, SNI y versiones TLS.

DNS puede causar un 502 si el gateway resuelve mal el destino o no puede alcanzarlo; no todo problema DNS del visitante produce ese código.

El upstream devuelve una respuesta no válida

La aplicación puede enviar encabezados mal formados o cerrar a mitad de la respuesta. Identifica el rechazo en el log del gateway, reproduce contra el upstream y corrige la salida.

Cómo comprobar que el error 502 quedó resuelto

Repite la solicitud y confirma el código esperado. Prueba la ruta pública y el origen, ejecuta varias comprobaciones y verifica que el error desapareció de los logs.

Comprueba una ruta crítica como login, checkout o API: un 200 en la página principal no prueba que todos los servicios se recuperaron.

Cómo detectar futuros errores 502 antes que los usuarios

Monitorea la URL pública y, cuando corresponda, un endpoint de salud. Conserva logs para relacionar incidentes con despliegues y acompaña la disponibilidad externa con métricas de aplicación.

DrMonitor registra el código HTTP de cada comprobación, incluido 502; considera fallidas las respuestas 5xx y agrupa fallos consecutivos en incidentes. Puede monitorear una URL pública específica. Con la regla de sitio caído y los canales habilitados, envía notificaciones de caída y recuperación por email, Telegram o SMS configurados.

[INSERTAR IMAGEN ORIGINAL] Recorte del dashboard de DrMonitor que muestre el intervalo de cinco minutos, la regla “Website Down” y los canales habilitados. Texto alternativo sugerido: Dashboard de DrMonitor con monitoreo cada cinco minutos y alertas de sitio caído. Pie: Línea base normal antes de ejecutar la prueba controlada con respuesta 502.

El monitoreo confirma qué devolvió el endpoint; los logs explican por qué. Para revisar otras señales, consulta la lista completa de monitoreo web.

Preguntas frecuentes sobre el error 502

¿Un error 502 puede afectar solo una página o API?

Sí. Un proxy puede enviar rutas a upstreams diferentes. Si /api/ falla y la página principal carga, prueba ese servicio y monitorea el endpoint crítico.

¿Cómo saber si el error 502 es del servidor?

Prueba otro navegador, dispositivo o red. Si el fallo se reproduce, probablemente esté en el gateway, proxy u origen; confírmalo con logs y una prueba autorizada al upstream.

¿Los problemas de DNS pueden causar un 502 Bad Gateway?

Sí, si el gateway obtiene una dirección incorrecta o no alcanza el destino resuelto. Verifica desde el entorno del gateway, no solo desde una laptop.

Empieza a monitorear errores HTTP

No esperes a que un visitante reporte el próximo fallo entre servidores. Empieza a monitorear tu sitio web con DrMonitor y conserva un historial con marcas de tiempo para compararlo con los logs de tu proxy y aplicación.