502 Bad Gateway: qué significa realmente y cómo solucionarlo
Abres tu sitio web y en lugar del contenido ves una página en blanco con el mensaje 502 Bad Gateway. Parece grave, pero en la mayoría de los casos la solución es sencilla. Veamos qué está pasando y cómo volver a poner tu sitio en marcha.
¿Qué significa realmente el 502?
Cuando un visitante solicita una página, la petición pasa por dos capas: un servidor web frontend (normalmente Nginx) y un servidor de aplicaciones backend (PHP-FPM, Apache, Node.js u otro). Nginx recibe la petición, 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 inválido o no recibió respuesta alguna. El backend se cayó, rechazó la conexión o devolvió algo que Nginx no pudo interpretar.
Un error muy común: 502 no significa que tu servidor esté caído. El servidor en sí funciona bien — el problema está en la aplicación que hay detrás de Nginx.
Causas más frecuentes
El servicio backend se ha detenido. Es la razón más habitual. PHP-FPM se cayó, Apache se quedó colgado o un proceso de Node.js murió sin avisar. Nginx no tiene con qué comunicarse.
Al servidor le falta memoria RAM. Cuando la memoria escasea, Linux puede matar automáticamente los procesos que más recursos consumen. Este mecanismo se llama OOM killer, y PHP-FPM o MySQL suelen ser sus primeras víctimas. Si esto ocurre con frecuencia, considera añadir un archivo de swap como medida de seguridad.
El pool de workers de PHP-FPM está saturado. Si tu sitio recibe más peticiones simultáneas de las que PHP-FPM puede gestionar, las nuevas peticiones se acumulan en cola y acaban agotando el tiempo de espera. Esto suele ocurrir cuando los robots de los buscadores rastrean tu sitio de forma muy agresiva — escribimos sobre cómo manejarlo 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 de PHP-FPM, verás errores 502 justo después de cualquier cambio.
Cómo diagnosticarlo
Para seguir los pasos a continuación, 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á funcionando
Verifica el estado de tu servicio backend:
sudo systemctl status php8.2-fpm
Sustituye php8.2-fpm por tu versión real de PHP o el nombre de tu servicio backend. Si la salida muestra inactive (dead) o failed, ahí está el problema. Reinícialo:
sudo systemctl restart php8.2-fpm
Luego comprueba el estado de nuevo para asegurarte de que se inició correctamente.
Paso 2. Revisa 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 usas FASTPANEL®, también puedes ver los logs directamente en la interfaz web: abre la tarjeta del sitio, ve a la sección «Logs» y consulta la pestaña «Frontend Error Log».
Estos son los mensajes de error más habituales y lo que significan:
connect() failed - Connection refused — el servicio backend no está activo. Reinícialo como se indica en el Paso 1.
connect() failed - No such file or directory — Nginx intenta conectarse a un socket Unix que no existe. Comprueba que la ruta del socket en tu configuración de Nginx coincide con la que realmente crea PHP-FPM.
upstream sent too big header — el backend devolvió cabeceras HTTP demasiado grandes para el búfer predeterminado. Añade estas líneas en la configuración de tu sitio 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 al servidor le esté faltando RAM. Comprueba qué la está consumiendo:
ps aux --sort=-%mem | head -10
Si la falta de memoria es la causa raíz, la solución temporal más rápida es añadir un archivo de swap. Sin embargo, el swap en disco es mucho más lento que la RAM y no debe considerarse una solución permanente. Si tu servidor se queda sin memoria con regularidad, es momento de optimizar tus aplicaciones o contratar un plan con más RAM.
Conclusión
Un 502 Bad Gateway es casi siempre un problema de backend: un servicio caído, workers agotados o memoria insuficiente. Comprueba el estado del backend, lee el log de errores de Nginx y revisa el uso de recursos. En la gran mayoría de los casos, encontrarás la respuesta en cuestión de minutos.
Si prefieres no gestionarlo solo, en kodu.cloud ofrecemos soporte técnico gratuito 24/7 con cada VPS y servidor dedicado. Todos nuestros clientes también reciben FASTPANEL® Extended sin coste adicional, lo que facilita enormemente el análisis de logs y la gestión de servicios a través de una interfaz web.