502 Bad Gateway: qué significa realmente y cómo solucionarlo
Abres tu sitio web y, en lugar de contenido, ves una página en blanco que dice 502 Bad Gateway. Parece alarmante, pero en la mayoría de los casos la solución es sencilla. Veamos qué está pasando y cómo recuperar tu sitio.
¿Qué significa realmente 502?
Cuando un visitante solicita una página, la solicitud normalmente pasa por dos capas: un servidor web de frontend (normalmente Nginx) y un servidor de aplicaciones de backend (PHP-FPM, Apache, Node.js u otro). Nginx recibe la solicitud, la reenvía al backend y espera una respuesta.
Un 502 Bad Gateway significa que Nginx intentó obtener una respuesta del backend, pero recibió algo no válido o no recibió ninguna respuesta. El backend falló, rechazó la conexión o devolvió algo que Nginx no pudo interpretar.
Un error común: 502 no significa que tu servidor esté caído. El propio servidor está bien; es la aplicación detrás de Nginx la que está teniendo problemas.
Causas más comunes
El servicio backend se ha detenido. Esta es la razón número uno. PHP-FPM falló, Apache se quedó colgado o un proceso de Node.js terminó silenciosamente. Nginx no tiene con qué comunicarse.
El servidor se está quedando sin RAM. Cuando la memoria escasea, Linux puede finalizar automáticamente los procesos que consumen muchos recursos. Este mecanismo se llama OOM killer, y PHP-FPM o MySQL suelen ser sus primeras víctimas. Si esto sucede con regularidad, considera añadir un archivo swap como medida de seguridad.
El pool de workers de PHP-FPM está agotado. Si tu sitio recibe más solicitudes simultáneas de las que PHP-FPM puede manejar, las nuevas solicitudes se ponen en cola y finalmente agotan el tiempo de espera. Esto suele pasar cuando los bots de los motores de búsqueda rastrean tu sitio de forma demasiado agresiva; escribimos sobre cómo manejar eso en nuestra guía para bloquear bots.
Socket o puerto mal configurado. Nginx espera encontrar PHP-FPM en un socket Unix o puerto TCP específico. Si la ruta en la configuración de Nginx no coincide con la configuración de PHP-FPM, verás errores 502 inmediatamente después de cualquier cambio.
Cómo diagnosticarlo
Para realizar los siguientes pasos, conéctate a tu servidor por SSH. Puedes aprender cómo hacerlo en nuestro artículo sobre SSH.
Paso 1. Comprueba si el backend está en ejecución
Comprueba el estado de tu servicio backend:
sudo systemctl status php8.2-fpm
Sustituye php8.2-fpm por tu versión real de PHP o por el nombre de tu servicio backend. Si la salida dice inactive (dead) o failed, ahí está el problema. Reinícialo:
sudo systemctl restart php8.2-fpm
Luego vuelve a comprobar el estado para asegurarte de que se inició correctamente.
Paso 2. Comprueba el log de errores de Nginx
El log de errores casi siempre te dice exactamente qué salió mal:
sudo tail -30 /var/log/nginx/error.log
Si estás usando FASTPANEL®, también puedes ver los logs directamente en la interfaz web: abre la tarjeta del sitio, ve a la sección "Logs" y revisa la pestaña "Frontend Error Log".
Estos son los mensajes de error más comunes y lo que significan:
connect() failed - Connection refused - el servicio backend no está en ejecución. Reinícialo como se muestra en el Paso 1.
connect() failed - No such file or directory - Nginx está intentando acceder a un socket Unix que no existe. Comprueba que la ruta del socket en tu configuración de Nginx coincide con la que PHP-FPM realmente crea.
upstream sent too big header - el backend devolvió encabezados HTTP demasiado grandes para el búfer predeterminado. Añade estas líneas a la configuración de tu sitio en Nginx dentro del bloque server:
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
Después de editar, prueba la configuración y recarga Nginx:
sudo nginx -t && sudo systemctl reload nginx
Paso 3. Comprueba los recursos del servidor
free -h
Si la columna available muestra menos de 100-200 MB de memoria libre, es probable que tu servidor se esté quedando sin RAM. Comprueba qué la está consumiendo:
ps aux --sort=-%mem | head -10
Si la presión de memoria es la causa raíz, la solución temporal más rápida es añadir un archivo swap. Sin embargo, la swap en disco es mucho más lenta que la RAM y no debe considerarse una solución permanente. Si tu servidor se queda sin memoria con regularidad, es hora de optimizar tus aplicaciones o pasarte a un plan con más RAM.
Conclusión
Un 502 Bad Gateway casi siempre es un problema del backend: un servicio que falló, workers agotados o memoria insuficiente. Comprueba el estado del backend, lee el log de errores de Nginx y revisa el uso de tus recursos. En la gran mayoría de los casos, encontrarás la respuesta en cuestión de minutos.
Si prefieres no lidiar con esto tú solo, en kodu.cloud ofrecemos soporte técnico gratuito 24/7 con cada VPS y servidor dedicado. Todos nuestros clientes también obtienen FASTPANEL® Extended sin coste adicional, lo que facilita significativamente el análisis de logs y la gestión de servicios a través de una interfaz web.