Saltar al contenido

5xx · Errores del servidor

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

El error 502 Bad Gateway significa que un servidor intermedio (nginx, un balanceador, Cloudflare) intentó contactar con la aplicación que hay detrás y recibió una respuesta inválida o la conexión fue rechazada. En la práctica casi siempre quiere decir que la aplicación de backend está caída, reiniciándose o escuchando en otro puerto.

Qué significa el código 502

En las arquitecturas actuales casi nunca hablas directamente con la aplicación: hay un proxy delante. Cuando ese proxy intenta pasarle tu petición al backend (PHP-FPM, Gunicorn, Node, un contenedor) y no obtiene una respuesta HTTP válida, te devuelve 502.

El log de nginx dice exactamente qué ha pasado: "connect() failed (111: Connection refused)" (no hay nada escuchando en ese puerto), "no live upstreams" (todos los backends caídos) o "upstream prematurely closed connection" (el backend se ha cerrado a mitad de respuesta, a menudo por falta de memoria).

Con Docker es muy típico: el proxy apunta a localhost:3000, pero dentro de un contenedor localhost es el propio contenedor. Hay que usar el nombre del servicio en la red de Docker (http://backend:3000) o la IP del host.

Causas habituales del error 502

  • La aplicación backend está parada, se ha caído o se está reiniciando.
  • Puerto o socket mal configurado en proxy_pass o fastcgi_pass.
  • Contenedor Docker al que el proxy no llega (redes distintas o uso de localhost).
  • El proceso muere por falta de memoria (OOM killer) a mitad de petición.
  • PHP-FPM sin procesos libres (pm.max_children demasiado bajo).
  • Cabeceras de respuesta demasiado grandes para los buffers de nginx.

Si eres visitante de la web

  • Espera un minuto y recarga: a menudo es un reinicio momentáneo del servidor.

Cómo solucionar el error 502

  • Comprueba que el backend está levantado: systemctl status, docker ps, pm2 list.
  • Prueba el backend directamente, sin el proxy: curl -i http://127.0.0.1:8000/.
  • Lee el log de nginx para ver si es Connection refused, timeout o cierre prematuro.
  • Busca en dmesg si el kernel ha matado el proceso por falta de memoria.
  • Si las cabeceras son grandes (cookies, JWT), sube proxy_buffer_size.

Configuración y comandos

Diagnóstico rápido

bash
sudo tail -n 30 /var/log/nginx/error.log
sudo ss -tlnp | grep 8000            # ¿hay algo escuchando?
curl -i http://127.0.0.1:8000/        # ¿responde sin el proxy?
sudo dmesg -T | grep -i "killed process"   # ¿OOM killer?

nginx con un backend en Docker Compose

nginx
location /api/ {
    proxy_pass http://backend:8001;   # nombre del servicio, no localhost
    proxy_set_header Host $host;
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
}

PHP-FPM con más procesos (www.conf)

ini
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Ejemplo de respuesta

http
HTTP/1.1 502 Bad Gateway
Server: nginx

# error.log:
# connect() failed (111: Connection refused) while connecting to upstream,
# upstream: "http://127.0.0.1:8000/"

Herramientas para comprobarlo

Preguntas frecuentes

¿Qué significa 502 Bad Gateway?

Que el servidor intermedio (proxy o CDN) no ha podido obtener una respuesta válida de la aplicación que hay detrás. Normalmente la aplicación está caída o mal conectada al proxy.

¿Qué diferencia hay entre 502 y 504?

502: el backend responde mal o rechaza la conexión. 504: el backend no responde a tiempo. El primero apunta a un servicio caído; el segundo, a uno lento.

¿Por qué da 502 con Docker?

Normalmente porque el proxy usa localhost para llegar a otro contenedor. Dentro de un contenedor, localhost es él mismo: usa el nombre del servicio de docker compose.

Códigos relacionados

Ver todos los códigos de estado HTTP