Un 502 Bad Gateway es un servidor diciéndote que otro servidor, en el que confiaba, respondió con algo que no podía usar. No es exactamente “el sitio está caído”, ni significa “hiciste algo mal”: una máquina en el medio le pidió a la máquina detrás de ella tu página, y lo que volvió fue basura, una puerta cerrada, o algo que no tenía sentido.
La palabra gateway es la pista. El servidor al que llegaste no es el que hace tu página; es un frente, un proxy inverso o un equilibrador de carga, parado frente a la aplicación que hace el trabajo real. Cuando ese frente obtiene una respuesta rota de detrás, lo único honesto que puede reportarte es que la respuesta fue mala. Que es exactamente lo que 502 significa.
La imagen de dos servidores
Casi todos los sitios de cualquier tamaño tienen al menos dos máquinas. Está la que tu navegador conecta primero (nginx, un edge de CDN, un equilibrador de carga en la nube), y detrás de ella el servidor de aplicaciones que realmente ejecuta el código y construye la página.
El frente toma tu solicitud y la pasa hacia atrás. La mayoría de las veces la aplicación responde limpiamente y el frente te entrega esa respuesta, invisiblemente. Un 502 es lo que ves cuando ese segundo paso falla: el frente preguntó, y la respuesta que obtuvo no era una respuesta HTTP válida que pudiera retransmitir.
Así que un 502 nunca es realmente sobre el servidor al que llegaste. Es un mensaje sobre el que no alcanzaste.
502 contra 504, que se confunden constantemente
Salen del mismo lugar (el servidor frontal, reportando sobre el que está detrás), y diferenciarlos reduce mucho la causa.
- 502 Bad Gateway
- El upstream respondió, y la respuesta fue inutilizable: una conexión rechazada, un proceso bloqueado, basura en la línea. Generalmente rápido
- 504 Gateway Timeout
- El upstream no respondió en absoluto dentro del tiempo permitido. Generalmente lento, y la pausa antes del error es en sí misma la pista
Aproximadamente: 502 es “dijo algo mal”, 504 es “aún no dijo nada”. Un 502 llega rápidamente y apunta a algo roto, bloqueado o rechazando conexiones; un 504 llega lentamente y apunta a algo atascado o sobrecargado. Si el error volvió casi instantáneamente, es mucho más probable un 502 que un 504, sin importar lo que diga la página.
Un detalle que la mayoría de artículos pasa por alto: los proveedores reetiquetar esto. Cloudflare devuelve 502 propio cuando tu origen envía una respuesta inválida, y su propio 520 para una respuesta tan malformada que no cabe en ningún código estándar. Detrás de un CDN, el número que ves puede ser el relato del CDN del mismo evento en lugar del de tu servidor.
Si eres el visitante
Recarga una vez, porque un 502 es frecuentemente un único worker bloqueado o un proceso atrapado en mid-restart, y la siguiente solicitud cae en uno sano. Si se resuelve, no hay nada que investigar.
Si persiste, la falta es del lado del sitio y genuinamente hay poco que puedas hacer además de decirles, porque ninguna configuración en tu navegador alcanza un proceso roto en su servidor. Antes de asumir que eres tú, confirma que no es local: la verificación más rápida es apuntar el comprobador de estado HTTP a la dirección, que solicita la página desde nuestro servidor en lugar del tuyo e informa el código que volvió. Si también ve el 502, el problema no es tu conexión.
Si es tu sitio
Un 502 dice que el frente no podía usar lo que la aplicación envió, así que la pregunta es qué hizo la aplicación. Solo hay unos pocos respuestas comunes.
El proceso de aplicación está caído o fallando. La causa más frecuente por un margen. El frente intenta conectarse y obtiene “conexión rechazada” porque nada está escuchando, o el proceso acepta la solicitud y muere a mitad de la respuesta. Verifica si la aplicación realmente está ejecutándose, y lee sus propios registros para ver un bloqueo o una terminación por falta de memoria en el momento del error (los registros del frente solo dirán que el upstream falló, nunca por qué).
Un desajuste de timeout entre las capas. Si la aplicación tarda más en responder que lo que el frente está dispuesto a esperar, algunos proxies reportan eso como 502 en lugar de 504, cerrando la conexión y llamando mala a la respuesta a mitad. Cuando un 502 se correlaciona con solicitudes lentas en lugar de bloqueos, mira aquí.
Un mal despliegue. Una nueva compilación que falla al iniciarse, escucha en el puerto equivocado, o responde con encabezados que el frente rechaza, convertirá cada solicitud en un 502 en el momento en que se pone en vivo. Si los errores comenzaron en un despliegue, ese es el primer lugar a mirar, y una reversión es más rápida que un diagnóstico.
Algo entre las capas. Un proxy_pass mal configurado, un nombre de host upstream que ya no se resuelve, un grupo de seguridad que silenciosamente dejó de permitir que el frente alcance la aplicación (la conexión nunca se completa y el frente reporta un bad gateway). Estos son los más lentos de encontrar porque nada se bloqueó; un enlace en la cadena simplemente dejó de llevar tráfico.
La razón por la cual estos son tan difíciles de investigar después
Un 502 frecuentemente se ha ido para cuando alguien mira. El worker bloqueado se reinicia, el despliegue se revierte, el pico de tráfico pasa, y el registro del frente solo dice que una solicitud upstream falló a las 09:14 (no qué dijo el upstream, no qué proceso, no por qué).
Lo que lo resuelve es evidencia capturada mientras está sucediendo: la solicitud que falló, el estado exacto, el tiempo, y qué estaba haciendo la persona cuando apareció. Un 502 que un usuario reporta una hora después, de memoria, es una conjetura. Un 502 con la solicitud fallida y su marca de tiempo adjuntos es una línea que puedes igualar contra el registro de aplicación e historial de despliegue y cerrar.
Session Replay
Extensión gratuita de Chrome. Un clic en la página que se comporta mal captura la captura de pantalla, la consola y el registro de red, y te entrega un enlace para pegar en el ticket.
El registro de red contiene la solicitud fallida con su 502 y el momento en que sucedió, guardado como salió mal en lugar de recordado después, que es la diferencia entre un reporte en el que alguien puede actuar y uno que primero tiene que reproducir.
En un párrafo
Un 502 Bad Gateway es un servidor de primera línea diciendo que el servidor detrás de él dio una respuesta que no podía usar (bloqueado, rechazado o malformado), y llega rápidamente, que es lo que lo diferencia del lento 504. Si estás visitando, recarga una vez y luego asume que es del lado de ellos. Si es tuyo, verifica si la aplicación está ejecutándose y qué registró, sospecha del último despliegue si el tiempo coincide, y captura la solicitud fallida mientras la tengas, porque un 502 es casi imposible de investigar una vez que ha pasado.