502 Bad Gateway

Qué significa este error y cómo reconocerlo

• El navegador muestra 502 Bad Gateway o Bad Gateway, a veces con la marca de Nginx, Apache, Cloudflare u otro proxy.
• El error afecta a varios usuarios, comienza después de un despliegue o cambio de configuración, o aparece durante un aumento del tráfico.
• Los fallos pueden ser intermitentes cuando se agotan los workers del backend, la memoria, la CPU o las conexiones a la base de datos.
• El registro del proxy informa de un fallo de conexión upstream, un timeout, una línea de estado ilegible, una respuesta mal formada, cabeceras demasiado grandes o un error de socket.
• Una solicitud directa al origen funciona, mientras que la misma solicitud a través de una CDN devuelve 502; esto apunta a problemas de acceso de la CDN al origen, firewall, TLS o routing.

Causas principales, ordenadas por probabilidad

1. Backend detenido o con fallos: PHP-FPM, Node.js, Gunicorn u otro proceso de la aplicación se ha detenido, entra en un ciclo de crashes o no se inició correctamente después del despliegue.
2. Sobrecarga o timeout del backend: se han agotado los workers, la memoria, la CPU, las conexiones a la base de datos u otra dependencia, por lo que el proxy no puede obtener una respuesta a tiempo.
3. Configuración upstream incorrecta: el proxy apunta al host, puerto, dirección del contenedor, socket Unix o ruta de aplicación equivocados.
4. Fallo de acceso al socket o al firewall interno: el proxy no puede llegar al backend debido a permisos del socket, una política de red, un firewall o un cambio en un security group.
5. Respuesta del backend no válida o demasiado grande: la aplicación envía una salida mal formada, una línea de estado inutilizable o cabeceras más grandes de lo que el proxy puede aceptar.
6. Fallo de la CDN al origen: una CDN no puede llegar al origen, el firewall del origen la bloquea o no puede establecer la conexión HTTPS que espera la configuración del origen.

Cómo solucionarlo

1. Identifica dónde se genera el 502

Comprueba si la página de error lleva la marca de Nginx, Apache, Cloudflare, una plataforma de hosting u otro intermediario. Determina si fallan todas las rutas o solo una ruta de la aplicación, y registra la hora del fallo y la URL afectada. Esto ayuda a asociar la solicitud con los registros correctos.

2. Comprueba el proceso backend y sus registros

Con acceso autorizado al servidor o al panel de hosting, comprueba si el proceso de la aplicación está en ejecución y acepta trabajo. Revisa sus registros en busca de ciclos de crashes, errores de aplicación fatales, terminación por falta de memoria, dependencias ausentes o fallos de inicio.

Por ejemplo, una comprobación de servicio de solo lectura podría ser:

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

Usa la versión de PHP-FPM y el gestor de procesos instalados, en lugar de copiar estos nombres sin cambios. Si el backend está detenido o entra en un ciclo de crashes, corrige primero la causa subyacente. Solo después considera reiniciar el servicio afectado mediante tu procedimiento normal de cambios; un reinicio puede interrumpir solicitudes y eliminar contexto útil de ejecución, así que confirma la autorización y captura antes los registros relevantes.

3. Lee el registro de errores del proxy

Relaciona la marca de tiempo del registro con una solicitud fallida. En Nginx, inspecciona el registro de errores configurado, que normalmente es /var/log/nginx/error.log. En Apache con mod_proxy o mod_proxy_fcgi, inspecciona el registro de errores de Apache.

Algunas distinciones útiles son:

• connect() failed: el proxy no puede llegar al upstream configurado.
• upstream timed out: el backend o una de sus dependencias es demasiado lento o está sobrecargado.
• upstream sent too big header: las cabeceras de respuesta superan el tamaño de los buffers configurados del proxy.
• Un error al leer la línea de estado: el backend cerró la conexión o devolvió una respuesta no válida.

La ubicación exacta del registro y el formato de los mensajes dependen del servidor y de la plataforma de hosting.

4. Verifica el host, puerto o socket upstream

Revisa la configuración del reverse proxy. En Nginx, comprueba el bloque proxy_pass o upstream. En Apache, comprueba ProxyPass, ProxyPassMatch y la configuración de conexión de PHP-FPM.

Usa una comprobación de escucha de solo lectura y una solicitud local cuando corresponda:

ss -tlnp
curl http://127.0.0.1:PORT

Sustituye PORT por el puerto configurado de la aplicación. Si la aplicación utiliza un socket Unix, verifica que la ruta exista y que el proceso del proxy pueda acceder a ella. En PHP-FPM, la configuración listen del pool debe coincidir con la dirección o el socket configurado en Apache o Nginx. No expongas públicamente un endpoint interno de prueba solo para realizar esta comprobación.

5. Investiga la sobrecarga, las dependencias y los timeouts

Si el backend está en ejecución pero los fallos coinciden con picos de tráfico o solicitudes lentas, comprueba la CPU, la memoria, el número de workers, las conexiones a la base de datos, la profundidad de la cola y los límites de recursos del panel de hosting. Un proceso puede estar en ejecución y, aun así, no poder aceptar más trabajo.

No aumentes los timeouts del proxy ni el tamaño de los buffers sin pruebas que lo justifiquen. Si el registro identifica cabeceras demasiado grandes, inspecciona la respuesta de la aplicación y revisa la configuración correspondiente de Nginx, proxy_buffer_size y proxy_buffers. Si es necesario cambiar la configuración, valídala y aplícala mediante el procedimiento de cambios aprobado, en lugar de recargar un proxy de producción sin autorización.

6. Compara el origen con la ruta de la CDN

Cuando Cloudflare u otra CDN está delante del sitio, prueba el origen directamente usando la dirección de origen correcta y la cabecera Host, con autorización para hacerlo. Compara el resultado con la solicitud pública.

• El origen también falla: investiga la aplicación, el proxy, el socket, el puerto, el firewall y las condiciones de recursos en el origen.
• El origen funciona, pero la CDN falla: comprueba las reglas del firewall entre la CDN y el origen, la accesibilidad del origen, el routing y el modo SSL/TLS de origen de la CDN. Confirma que el origen ofrece el protocolo y la configuración de certificados que espera la CDN.

7. Repite la prueba después de corregir la causa

Primero confirma que el origen devuelve la respuesta esperada. Después prueba la solicitud a través del reverse proxy o la CDN. Si solo fallan algunas URL, compara sus rutas de aplicación, el tamaño de la respuesta, los requisitos de autenticación y las dependencias del backend, en lugar de tratar el problema como una interrupción general del servicio.

8. Comprueba los límites del panel de hosting

En cPanel, Plesk u otros servicios de hosting compartido similares, revisa los registros de PHP-FPM y de uso de recursos. La cuenta puede estar alcanzando un límite de procesos, memoria o concurrencia impuesto por el proveedor. Si no se puede cambiar el límite, facilita al proveedor las horas de los fallos, la ruta afectada y el mensaje de registro relevante para que pueda revisar los registros de la infraestructura.

Prevención y cómo verificar la solución

• Ejecuta la aplicación bajo supervisión de procesos y monitoriza los crashes repetidos, en lugar de depender únicamente de reinicios automáticos.
• Monitoriza la memoria, la CPU, el uso de workers, las conexiones a la base de datos, la profundidad de la cola y los límites del panel de hosting antes de que afecten a las solicitudes.
• Configura timeouts deliberados y compatibles entre la aplicación, el proxy, el balanceador de carga y la CDN; no utilices timeouts más largos para ocultar un backend en mal estado.
• Verifica el puerto o socket esperado de la aplicación después de los despliegues y cambios de configuración.
• Prueba rutas representativas directamente contra el origen y a través de la CDN después de cambiar el TLS del origen, las reglas del firewall o la configuración del proxy.
• Conserva los registros del proxy y de la aplicación con marcas de tiempo sincronizadas para poder relacionar las respuestas 502 intermitentes con eventos del backend.
• Documenta el servicio responsable, la dirección upstream, los permisos del socket y el procedimiento de recuperación aprobado para el entorno.

Preguntas frecuentes