Un error 502 Bad Gateway ocurre cuando un servidor actuando como gateway o proxy recibe una respuesta inválida de un servidor upstream. Esto típicamente sucede en arquitecturas distribuidas donde un load balancer, CDN o API gateway está entre clientes y servidores de aplicación. Entre todos los códigos de estado HTTP, el 502 es uno de los más disruptivos porque apunta a una falla entre capas—no en el cliente o el origen final por separado.
Qué Significa 502 Bad Gateway
Per RFC 9110, 502 indica “el servidor, mientras actuaba como gateway o proxy, recibió una respuesta inválida de un servidor upstream que accedió mientras intentaba completar la solicitud.”
502 vs 503 vs 504
| Código | Significado | Causa Raíz |
|---|---|---|
| 502 Bad Gateway | Respuesta inválida del upstream | Crash de aplicación, respuesta malformada, incompatibilidad de protocolo |
| 503 Service Unavailable | Servidor no puede manejar solicitud | Sobrecarga, mantenimiento, agotamiento de recursos |
| 504 Gateway Timeout | Sin respuesta del upstream | Upstream muy lento, timeout excedido |
Causas Comunes de 502 Bad Gateway
- Servidor de Aplicación No Está Ejecutándose
- Servidor de Aplicación Crasheó
- Incompatibilidad de Protocolo
- Respuesta Muy Grande
- Connection Reset
- Puerto o Dirección Incorrecta
Troubleshooting de Errores 502
Paso 1: Identifica Qué Capa Generó el 502
Paso 2: Verifica Salud del Servidor Upstream
Paso 3: Verifica Logs del Proxy/Gateway
En Azion, accede a Real-Time Events y filtra por status = 502. El campo upstream_response_time indica cuánto tardó el upstream, y upstream_cache_status confirma si el error vino de la capa de caché o del origen.
Paso 4: Verifica Conectividad de Red
Paso 5: Compara Configuraciones de Timeout
Cómo Corregir Errores 502
- Corrige Problemas del Servidor de Aplicación
- Corrige Configuración de Nginx
- Corrige Health Checks
- Implementa Circuit Breakers
Preguntas Frecuentes
¿Cuál es la diferencia entre 502 y 504? 502 significa que el upstream envió una respuesta inválida. 504 significa que el upstream no respondió (timeout).
¿Por qué 502 ocurre después del deploy? Causas comunes: aplicación no inicia, puerto incorrecto, variables de entorno faltantes.
¿Debo reintentar en 502? Solo para métodos idempotentes (GET, PUT, DELETE). Usa backoff exponencial.