Los códigos de estado HTTP son códigos de respuesta de tres dígitos que los servidores devuelven para comunicar el resultado de las solicitudes. En sistemas distribuidos, interpretarlos correctamente requiere entender la ruta completa de la solicitud: cliente, CDN, balanceador de carga, servidor de aplicación y dependencias upstream.
Cómo se comportan los códigos de estado en sistemas distribuidos
Una sola solicitud atraviesa múltiples componentes antes de llegar al origen. Cada componente contribuye o modifica el código de estado devuelto al cliente.
Cliente ──► CDN ──► Balanceador ──► Aplicación ──► Base de Datos │ │ │ │ │ │ Intercepta Enruta a Procesa Puede expirar │ 4xx/5xx nodo saludable solicitud o fallar │ del origen y devuelve │ 200/4xx/5xxEn esta arquitectura, el código de estado que el cliente ve puede venir de cualquier capa. Un 502 Bad Gateway del CDN significa que el origen devolvió una respuesta inválida. Un 504 Gateway Timeout significa que el origen no respondió dentro de la ventana de timeout configurada.
Flujo de troubleshooting
┌─────────────────────────────┐ │ Identifique el código │ └──────────┬──────────────────┘ ▼ ┌─────────────────────────────┐ │ Clase: 4xx o 5xx? │ └──────────┬──────────────────┘ ▼ ┌─────────────────────────────┐ ┌────┤ ¿Quién lo generó? │ │ │ - Logs de borde del CDN │ │ │ - Logs de acceso del origen│ │ └──────────┬──────────────────┘ │ ▼ │ ┌─────────────────────────────┐ │ │ Reproduzca la solicitud │ │ │ Aísle variables: │ │ │ - Headers │ │ │ - Método │ │ │ - Cuerpo │ │ │ - Autenticación │ │ └──────────┬──────────────────┘ │ ▼ │ ┌─────────────────────────────┐ │ │ Verifique dependencias: │ │ │ - API upstream │ │ │ - Base de datos │ │ │ - Caché │ │ └──────────┬──────────────────┘ │ ▼ │ ┌─────────────────────────────┐ └────┤ Aplique corrección y verifique └─────────────────────────────┘Patrones de código de estado por capa
| Capa | Códigos comunes | Significado |
|---|---|---|
| CDN | 502, 504, 403 | Origen inaccesible, timeout de origen, bloqueo WAF |
| Balanceador | 503, 502, 504 | Sin upstream saludable, respuesta inválida del upstream, timeout |
| Aplicación | 200, 201, 400, 401, 403, 404, 409, 422, 429, 500 | Resultado del procesamiento |
| Autenticación | 401, 403 | Credenciales ausentes, permisos insuficientes |
| Base de datos | 500, 503 (propagado) | Fallo de query, pool de conexiones agotado |
| API upstream | 502 (propagado como 502 o mapeado) | Fallo de dependencia |
Diagnósticos principales para cada código de estado
Patrones 4xx:
- 400: Inspeccione formato del cuerpo de la solicitud, headers obligatorios, tipos de parámetros
- 401: Verifique header Authorization, expiración de token, formato del token
- 403: Verifique permisos para el recurso y método específicos
- 404: Confirme que la ruta URL coincide exactamente con la definición de ruta (barras, mayúsculas/minúsculas)
- 405: Verifique método HTTP contra métodos permitidos para el endpoint
- 409: Verifique modificaciones concurrentes, claves de idempotencia
- 422: Valide contra reglas de negocio, no solo restricciones de esquema
- 429: Verifique header Retry-After, evalúe configuración de límite de tasa
Patrones 5xx:
- 500: Verifique logs del servidor para excepciones no manejadas. Confirme si ningún despliegue reciente introdujo problemas.
- 502: Verifique logs del servidor upstream. Asegúrese de que el upstream devuelve respuestas HTTP válidas.
- 503: Verifique despliegue en curso, picos de tráfico, agotamiento de recursos
- 504: Verifique tiempo de respuesta del upstream. Ajuste configuración de timeout si el upstream es lento pero confiable.
Métricas y Medición
- Tiempo hasta el primer byte (TTFB): Tiempo hasta que los headers de respuesta llegan (meta: <500ms p95 para contenido dinámico)
- Tasa de consumo de error budget: Porcentaje de errores 5xx permitidos consumidos a lo largo del tiempo (meta: <10% del error budget por día)
- Distribución de códigos de estado: Porcentaje de cada código de respuesta sobre el total de solicitudes
Referencias del sector:
- Tasas de 5xx por encima de 0,1% requieren investigación (directrices Google SRE)
- TTFB promedio para respuestas en caché en el borde: 20-50ms (benchmarks de proveedores CDN, 2025)
- TTFB promedio para respuestas no cacheadas del origen: 200-800ms (HTTP Archive, 2025)
Errores Comunes y Correcciones
Error: Tratar todos los errores 5xx como bugs de aplicación Corrección: Clasifique errores 5xx por capa (CDN, balanceador, aplicación, upstream). Un 504 es típicamente un problema de infraestructura, no de código.
Error: No registrar contexto suficiente con códigos de estado Corrección: Registre ID de solicitud, ID de usuario, endpoint, método, tiempo de respuesta y código de estado upstream junto con cada respuesta.
Error: Mezclar budgets de error de 4xx y 5xx Corrección: Los errores 4xx indican mal comportamiento del cliente y no deben consumir budgets de error del servidor. Monitoree 4xx y 5xx independientemente.
Error: Ignorar respuestas 429 en el código cliente Corrección: Implemente backoff exponencial y respete headers Retry-After en todos los clientes.
Error: Tratar 502 y 503 de la misma forma Corrección: 502 significa respuesta inválida del upstream. 503 significa que el servicio en sí no está disponible. Cada uno requiere un camino de diagnóstico diferente.
Casos de uso de troubleshooting
Respuesta a picos de tráfico
Cuando una campaña de marketing genera tráfico inesperado, las respuestas 503 y 429 aumentan. Verifique configuración de auto-scaling, límites de tasa y tasa de acierto de caché del CDN. Aumente TTL de caché para activos estáticos como mitigación a corto plazo.
Rollback de despliegue
Un nuevo release introduce errores 500. Compare tasas de error antes y después del despliegue usando logs de solicitud. Si la tasa de 5xx aumenta 2x o más, revierta e investigue el diff.
Dependencia de API de terceros
Una API socia upstream devuelve 503. Su servicio puede devolver 502 o 503 a los clientes. Implemente circuit breakers y respuestas de fallback para evitar fallos en cascada.
Compatibilidad con aplicación móvil
Una actualización de iOS envía un nuevo header que su servidor no espera, causando errores 400 para un subconjunto de usuarios. Registre headers y cuerpo de la solicitud para cada respuesta 4xx para detectar desviaciones de contrato de API.
Preguntas Frecuentes
¿Cómo distinguir entre un 502 generado por el CDN y un 502 generado por el origen? Verifique logs de acceso del CDN y logs de acceso del origen simultáneamente. Si los logs del origen muestran la solicitud con respuesta no 5xx, el CDN generó el 502. Si los logs del origen muestran un 5xx o están ausentes (timeout), el origen lo causó.
¿Qué significa un 503 durante un despliegue? Significa que el balanceador de carga marcó la instancia como no saludable mientras se iniciaba. Asegúrese de que las verificaciones de salud devuelvan 200 solo después de que la aplicación esté completamente inicializada, no inmediatamente después de que el proceso inicie.
¿Cómo rastrear un código de estado a través de múltiples servicios? Use un correlation ID propagado a través de headers. Cada servicio registra el código de estado que devuelve junto con el correlation ID. Agregue logs por correlation ID para ver la cadena completa.
¿Debo reintentar después de una respuesta 429? Sí, pero solo después del retraso especificado en el header Retry-After. Implemente jitter y backoff exponencial para evitar tormentas de reintento.
¿Por qué mi balanceador devuelve 503 cuando la aplicación está saludable? Verifique la configuración de la verificación de salud. El balanceador puede usar un puerto, ruta o protocolo diferente de la aplicación. Asegúrese de que el endpoint de salud devuelva 200 dentro del timeout.
¿Cuál es la diferencia entre 502 y 504 en el contexto de CDN? 502 significa que el CDN recibió una respuesta malformada del origen. 504 significa que el origen no respondió dentro del timeout configurado del CDN. Ambos indican problemas de origen pero requieren correcciones diferentes de timeout o validación de respuesta.
¿Cómo depurar errores 5xx intermitentes? Ejecute la misma solicitud múltiples veces y compare respuestas. Si 5xx ocurre aleatoriamente, verifique agotamiento de recursos (pools de conexión, hilos, conexiones de base de datos) o pausas de garbage collection usando herramientas de profiling de la aplicación.
¿Qué código de estado devolver cuando una dependencia está fuera de servicio? Devuelva 502 Bad Gateway. No lo enmascare como 500 o 503. 502 señala correctamente que el error se originó de una dependencia, no del servicio en sí.
¿Cómo configurar alertas de monitoreo para códigos de estado? Alerta para tasa de 5xx por encima de 0,1% en 5 minutos. Alerta para tasa de 4xx por encima de 10% del total de solicitudes. Alerta para caídas súbitas en la tasa de 2xx. Defina alertas separadas para cada endpoint crítico.
¿Cuál es la relación entre códigos de estado y SLIs? Los códigos de estado son una entrada directa para SLIs de disponibilidad. Cuente 5xx y 4xx apropiados (timeouts) como fallo. Divida respuestas exitosas por el total de solicitudes para calcular disponibilidad. Use esto para rastrear cumplimiento con SLOs.
Cómo se aplica en la práctica
En sistemas de producción, un solo código de estado rara vez cuenta la historia completa. El mismo 502 puede significar un timeout de origen, una respuesta inválida del upstream o una mala configuración del CDN. Rastrear un código de estado a través del sistema importa más que reconocerlo.
Los equipos que manejan efectivamente la respuesta a incidentes mantienen runbooks para cada patrón de código de estado. Estos runbooks especifican qué logs verificar primero, qué métricas comparar y qué acciones tomar según el patrón. Esto reduce el tiempo medio de resolución de horas a minutos.
Cómo implementar en Azion
Azion proporciona herramientas para rastrear códigos de estado a través de la ruta completa de la solicitud:
- Edge Logs: Exporte logs en tiempo real via Azion Data Streaming para ver códigos de estado en cada capa
- Application Analytics: Use Azion Metrics para filtrar por clase de código de estado e identificar patrones anómalos
- Configuración de Respuesta de Error: Personalice respuestas 4xx y 5xx devueltas por el borde de Azion, incluyendo sugerencias de reintento
- Reglas de Alerta: Configure alertas basadas en umbrales para tasas de 5xx con granularidad por aplicación
Más información en la Documentación de Azion.
Fuentes:
- IETF. “HTTP Semantics.” RFC 9110. 2022.
- Google SRE. “Service Level Objectives.” 2023.
- HTTP Archive. “Web Almanac.” 2025.
- AWS. “Troubleshooting 5xx Errors.” 2025.