Un error 502 Bad Gateway significa que un servidor que actúa como gateway o proxy recibió una respuesta no válida del servidor que tiene detrás. El visitante llegó a algo, normalmente nginx, Apache, un balanceador de carga o una CDN, pero esa capa no consiguió una respuesta correcta de tu aplicación. La aplicación se ha caído, se está reiniciando, escucha en otro sitio o cerró la conexión a medias.
Por eso un 502 es un mensaje sobre dos servidores, no sobre uno. Esta guía te enseña a saber qué capa lo devolvió, a solucionar las causas habituales y a enterarte del próximo 502 antes que tus clientes.
Qué te dice un 502
La mayoría de los sitios web tienen al menos dos capas entre el visitante y el código. Delante hay una CDN o un balanceador de carga, un servidor web como nginx termina la conexión y un proceso de aplicación, como PHP-FPM, Node.js, Gunicorn o un servidor Java, genera la página. Cada capa reenvía la petición a la siguiente y devuelve la respuesta.
Un 502 aparece cuando una de esas capas reenvía una petición y no recibe nada aprovechable. Compáralo con los otros errores de gateway:
502 Bad Gateway: el servidor upstream respondió algo no válido, reinició la conexión o la rechazó.
503 Service Unavailable: el servicio está sobrecargado, en mantenimiento o no tiene ningún servidor sano al que enviar la petición.
504 Gateway Timeout: el servidor upstream no respondió a tiempo.
Así que un 502 suele significar roto o parado, y un 504 suele significar lento. Nuestra chuleta de códigos de estado HTTP recoge el resto de la familia, y la guía de los errores 503 trata la sobrecarga y el mantenimiento.
Encuentra la capa que devolvió el 502
Antes de cambiar nada, averigua quién respondió. La página de error y las cabeceras de la respuesta suelen decirlo sin rodeos:
curl -sI https://www.example.com/checkout
HTTP/2 502
server: cloudflare
cf-ray: 8d2f1c3a5b7e4a21-ARN
server: cloudflare con una página de error de Cloudflare que nombra tu host: Cloudflare llegó a tu origen, y el origen falló.
server: nginx o Apache con una página de error sencilla: tu propio servidor web no pudo llegar a la aplicación que tiene detrás.
server: awselb/2.0 u otro balanceador de carga: el balanceador no recibió una respuesta válida de ningún destino, o del que eligió.
Después compara con una petición que se salte la capa exterior. Envíala directamente al origen o al puerto de la aplicación en el propio servidor:
curl -sI –resolve www.example.com:443:203.0.113.10 https://www.example.com/checkout
curl -sI http://127.0.0.1:3000/checkout
Si la aplicación responde en local pero no a través del proxy, revisa la configuración del proxy. Si tampoco responde en local, el problema es la aplicación.
Causas habituales y cómo solucionarlas
El proceso de la aplicación se ha caído o se está reiniciando
Es la causa más común. El proceso que hay detrás del proxy se quedó sin memoria, sufrió una excepción no gestionada o lo mataron, y el proxy no tiene con quién hablar. nginx lo registra con claridad:
connect() failed (111: Connection refused) while connecting to upstream,
upstream: «http://127.0.0.1:3000/checkout»
Comprueba si el proceso está en marcha y por qué se paró:
systemctl status myapp
journalctl -u myapp –since «30 min ago»
dmesg -T | grep -i «killed process»
Una línea del OOM killer del kernel significa que el servidor se quedó sin memoria. Reiniciar recupera el sitio, pero la solución real es más memoria, menos workers o encontrar y corregir una fuga. Asegúrate de que el servicio se reinicia solo tras una caída, por ejemplo con Restart=on-failure en su unidad de systemd.
PHP-FPM está caído o sin workers
En sitios PHP, nginx pasa las peticiones a PHP-FPM a través de un socket o un puerto. Si PHP-FPM está parado, la ruta del socket es incorrecta o los permisos del socket no dejan entrar a nginx, todas las páginas PHP devuelven 502:
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)
Ese mensaje suele aparecer tras actualizar PHP: nginx sigue apuntando al socket de la versión antigua. Apunta fastcgi_pass al nuevo socket y recarga nginx. Si el log dice en cambio server reached pm.max_children, todos los workers están ocupados, a menudo esperando a una base de datos lenta o a una API externa. Sube el límite solo si al servidor le sobra memoria; si no, busca qué mantiene ocupados a los workers.
Dirección o puerto upstream incorrectos
Tras una migración, la reconstrucción de un contenedor o un cambio de puerto, el proxy puede seguir reenviando a la dirección antigua. El log de errores muestra la dirección que intentó. Compárala con aquella en la que escucha realmente la aplicación:
ss -ltnp | grep -E ‘:(3000|8000|9000)’
En Docker y Kubernetes, la causa suele ser un nombre de servicio que ya no se resuelve, un contenedor que escucha en 127.0.0.1 dentro del contenedor en lugar de en 0.0.0.0, o una readiness check que marca todos los pods como no preparados.
El upstream cerró la conexión antes de tiempo
upstream prematurely closed connection while reading response header significa que la aplicación aceptó la petición y luego colgó. Los motivos típicos son una caída a mitad de la petición, un worker eliminado por superar su propio límite de tiempo, como el –timeout de Gunicorn o el max_execution_time de PHP, y conexiones keep-alive que la aplicación cierra antes de lo que espera el proxy. Ajusta los timeouts para que el proxy espere un poco más que la aplicación, nunca al revés, y mira qué peticiones son tan lentas como para llegar al límite.
Cabeceras de respuesta demasiado grandes
Las cookies grandes o muchas cabeceras Set-Cookie pueden superar el búfer de nginx para las cabeceras de respuesta del upstream. Entonces nginx registra upstream sent too big header while reading response header from upstream y devuelve 502. Aumenta los búferes con cuidado:
proxy_buffer_size 16k;
proxy_buffers 8 16k;
# for PHP-FPM
fastcgi_buffer_size 32k;
fastcgi_buffers 8 16k;
Después averigua por qué crecieron las cabeceras. Una cookie que crece en cada visita es un bug que merece la pena corregir.
La CDN no puede comunicarse con tu origen
Cuando una CDN o un balanceador de carga devuelve 502, revisa qué hay entre él y tu servidor. Un firewall que bloquea los rangos de direcciones de la CDN, un certificado de origen que la CDN no acepta, un origen que solo habla HTTP/1.0 o que cierra las conexiones demasiado pronto, o un registro DNS que apunta a un servidor antiguo acaban todos igual. Prueba el origen directamente, como se muestra arriba, y revisa el firewall y la configuración TLS en ambos lados.
Errores 502 durante los despliegues
Si los 502 aparecen durante diez o veinte segundos cada vez y siempre en torno a una release, los causa el propio despliegue. El proceso antiguo se para, el nuevo tarda unos segundos en arrancar y todas las peticiones de ese intervalo fallan. La solución es un orden de despliegue en el que siempre haya algo listo para responder:
Arranca la nueva versión junto a la antigua.
Espera a que pase su health check. Nuestra guía para crear un endpoint de health check explica qué debe comprobar.
Pasa el tráfico a la nueva versión.
Deja que la versión antigua termine las peticiones que tiene y luego párala.
Los gestores de procesos y los orquestadores lo permiten como recargas progresivas o sin tiempo de inactividad. Úsalas en lugar de un simple reinicio.
Cómo detecta la monitorización los errores 502
Un 502 suele ser breve. Un despliegue provoca veinte segundos de errores, un worker se cae y se reinicia, una caché oculta el problema a la mayoría de los visitantes. Cuando alguien abre el sitio, ya funciona otra vez, pero un cliente que estaba en pleno checkout vio el error.
Un monitor de uptime solicita tus páginas de forma programada y registra el código de estado y el tiempo de respuesta de cada comprobación. Un 502 es una comprobación fallida. Lo importante es lo que pasa después:
Confirma el fallo. Una sola petición fallida puede ser un fallo puntual. Uptimecheck comprueba hasta cada minuto desde Estocolmo, Londres y Nueva York, y confirma cada fallo desde una segunda ubicación antes de abrir una incidencia, para que un reinicio puntual no despierte a nadie.
Muestra las pruebas. La incidencia incluye la respuesta fallida, así que ves el código de estado, la cabecera server y la página de error, y una captura de pantalla de lo que vieron los visitantes. Cuando el servidor no respondió en absoluto, obtienes en su lugar la ruta de red.
Avisa a las personas adecuadas. Las alertas llegan por email, Slack, Microsoft Teams, PagerDuty, webhooks y los demás canales de alerta que usa tu equipo.
Vigila algo más que la página de inicio. A menudo una CDN la tiene en caché y sigue funcionando mientras el checkout, el inicio de sesión y la API devuelven 502. Añade monitores de uptime para las páginas que generan ingresos y monitores de API para los endpoints a los que llaman tus apps. Cuando el 502 viene de una aplicación que se quedó sin memoria, la monitorización de servidores muestra la curva de memoria junto a la caída.
Checklist del error 502
Lee la cabecera server y la página de error para ver qué capa devolvió el 502.
Solicita directamente el origen y el puerto de la aplicación para acotarlo.
Lee el log de errores del proxy en la misma marca de tiempo: conexión rechazada, cerrada antes de tiempo o cabecera demasiado grande.
Comprueba que el proceso de la aplicación está en marcha y, si no, por qué se paró.
Compara la dirección, el socket y el puerto upstream con aquellos en los que escucha la aplicación.
Ajusta los timeouts para que el proxy espere más que la aplicación.
Despliega arrancando la nueva versión antes de parar la antigua.
Monitoriza las páginas y endpoints clave cada minuto y confirma cada fallo antes de alertar.