Los códigos de estado HTTP son códigos de respuesta de tres dígitos que los servidores devuelven para comunicar el resultado de un request. En sistemas distribuidos, interpretarlos correctamente requiere entender toda la ruta del request: cliente, CDN, load balancer, servidor de aplicación y dependencias upstream.
Resumen rápido — En un sistema distribuido, un mismo código de estado HTTP puede originarse en capas distintas: CDN, load balancer, aplicación o una dependencia upstream. Un 502 Bad Gateway significa que el origen devolvió una respuesta inválida; un 504 Gateway Timeout significa que el origen no respondió a tiempo. Clasificar los errores 5xx por capa, en lugar de tratarlos todos como bugs de aplicación, reduce el tiempo medio de resolución de horas a minutos. Los equipos que mantienen runbooks por patrón de código de estado (qué logs revisar primero, qué métricas comparar) diagnostican incidentes de forma consistente y repetible.
Última actualización: 2026-08-08
Cómo se comportan los códigos de estado HTTP en sistemas distribuidos
Un solo request atraviesa múltiples componentes antes de llegar a su origen. Cada componente contribuye o modifica el código de estado devuelto al cliente.
Cliente ──► CDN ──► Load Balancer ──► Aplicación ──► Base de datos │ │ │ │ │ │ Intercepta Enruta a un Procesa el Puede tener │ 4xx/5xx nodo saludable request timeout o fallar │ del origen y devuelve │ 200/4xx/5xxEn esta arquitectura, el código de estado que ve el cliente puede venir de cualquier capa. Un 502 Bad Gateway de la 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
┌─────────────────────────┐ │ Identificar el código │ │ de estado │ └──────────┬──────────────┘ ▼ ┌─────────────────────────┐ │ ¿Clase: 4xx o 5xx? │ └──────────┬──────────────┘ ▼ ┌─────────────────────────┐ ┌────┤ ¿Quién lo generó? │ │ │ - Edge logs de la CDN │ │ │ - Access logs del │ │ │ origen │ │ └──────────┬──────────────┘ │ ▼ │ ┌─────────────────────────┐ │ │ Reproducir el request │ │ │ Aislar variables: │ │ │ - Headers │ │ │ - Método │ │ │ - Body │ │ │ - Auth │ │ └──────────┬──────────────┘ │ ▼ │ ┌─────────────────────────┐ │ │ Revisar dependencias: │ │ │ - API upstream │ │ │ - Base de datos │ │ │ - Caché │ │ └──────────┬──────────────┘ │ ▼ │ ┌─────────────────────────┐ └────┤ Aplicar corrección y │ │ verificar │ └─────────────────────────┘Patrones de códigos de estado por capa
| Capa | Códigos comunes | Significado |
|---|---|---|
| CDN | 502, 504, 403 | Origen inaccesible, timeout del origen, bloqueo de WAF |
| Load Balancer | 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 del request |
| Autenticación | 401, 403 | Credenciales faltantes, permisos insuficientes |
| Base de datos | 500, 503 (propagado) | Fallo de consulta, agotamiento del connection pool |
| API upstream | 502 (propagado o mapeado como tal) | Fallo de dependencia |
Diagnóstico para cada código de estado
Patrones 4xx:
- 400: inspecciona el formato del body del request, los headers requeridos y los tipos de parámetro
- 401: revisa el header Authorization, la expiración del token, el formato del token
- 403: verifica los permisos para el recurso y el método específico
- 404: confirma que el path de la URL coincide exactamente con la definición de la ruta (slashes finales, mayúsculas)
- 405: verifica el método HTTP contra los métodos permitidos para el endpoint
- 409: revisa si hay modificaciones concurrentes, idempotency keys
- 422: valida contra las reglas de negocio, no solo las restricciones del schema
- 429: revisa el header Retry-After, evalúa la configuración del rate limit
Patrones 5xx:
- 500: revisa los logs del servidor en busca de excepciones no manejadas. Verifica que ningún deployment reciente haya introducido problemas.
- 502: revisa los logs del servidor upstream. Asegúrate de que el upstream devuelva respuestas HTTP válidas.
- 503: revisa si hay un deployment en curso, picos de tráfico, agotamiento de recursos
- 504: revisa el tiempo de respuesta del upstream. Ajusta la configuración del timeout si el upstream es lento pero confiable.
Métricas y medición
- Time to first byte (TTFB): tiempo hasta que llegan los headers de respuesta (objetivo: menor a 500ms p95 para contenido dinámico)
- Tasa de consumo del error budget: porcentaje de errores 5xx permitidos consumidos en el tiempo (objetivo: menor al 10% del error budget por día)
- Distribución de códigos de estado: desglose de todos los códigos de respuesta como porcentaje del total de requests
Benchmarks del sector:
- Tasas de 5xx por encima de 0.1% requieren investigación (guías de Google SRE)
- TTFB promedio para respuestas cacheadas en el edge: 20-50ms (benchmarks de proveedores de CDN, 2025)
- TTFB promedio para respuestas del origen sin cachear: 200-800ms (HTTP Archive, 2025)
Errores comunes y cómo corregirlos
Error: tratar todos los errores 5xx como bugs de aplicación Corrección: clasifica los errores 5xx por capa (CDN, load balancer, aplicación, upstream). Un 504 suele ser un problema de infraestructura, no un bug de la app.
Error: no registrar suficiente contexto junto con los códigos de estado Corrección: registra request ID, user ID, endpoint, método, tiempo de respuesta y código de estado del upstream junto a cada respuesta.
Error: mezclar los error budgets de 4xx y 5xx Corrección: los errores 4xx indican mal comportamiento del cliente y no deberían consumir el error budget del servidor. Rastrea 4xx y 5xx de forma independiente.
Error: ignorar las respuestas 429 en el código del cliente Corrección: implementa exponential backoff y respeta los headers Retry-After en todos los clientes.
Error: tratar 502 y 503 de forma idéntica Corrección: 502 significa una respuesta inválida del upstream. 503 significa que el propio servicio no está disponible. Cada uno requiere una ruta de diagnóstico distinta.
Casos de uso de troubleshooting
Respuesta a un pico de tráfico
Cuando una campaña de marketing genera tráfico inesperado, aumentan las respuestas 503 y 429. Revisa la configuración de auto-scaling, los umbrales de rate limit y el cache hit ratio de la CDN. Aumenta el TTL de caché para assets estáticos como mitigación a corto plazo.
Rollback de deployment
Un release nuevo introduce errores 500. Compara las tasas de error antes y después del deployment usando los logs de requests. Si la tasa de 5xx aumenta 2x o más, haz rollback e investiga el diff.
Dependencia de API de terceros
Una API de un socio upstream devuelve 503. Tu servicio puede devolver 502 o 503 a los clientes. Implementa circuit breakers y respuestas de fallback para prevenir fallos en cascada.
Compatibilidad con app móvil
Una actualización de iOS envía un header nuevo que tu servidor no espera, causando errores 400 para un subconjunto de usuarios. Registra los headers y el body del request para cada respuesta 4xx para detectar desviaciones en el contrato de la API.
Preguntas frecuentes
¿Cómo distingo un 502 generado por la CDN de uno generado por el origen? Revisa simultáneamente los logs de acceso de la CDN y del origen. Si los logs del origen muestran el request con una respuesta que no es 5xx, la 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 deployment? Significa que el load balancer marcó la instancia como no saludable mientras arrancaba. Asegúrate de que los health checks devuelvan 200 solo después de que la aplicación esté completamente inicializada, no inmediatamente después de que arranca el proceso.
¿Cómo rastreo un código de estado a través de múltiples servicios? Usa un correlation ID propagado a través de los headers. Cada servicio registra el código de estado que devuelve junto con el correlation ID. Agrega los logs por correlation ID para ver la cadena completa.
¿Debería reintentar una respuesta 429? Sí, pero solo después del retraso especificado en el header Retry-After. Implementa jitter y exponential backoff para evitar retry storms.
¿Por qué mi load balancer devuelve 503 cuando la aplicación está saludable? Revisa la configuración del health check. El load balancer puede usar un puerto, path o protocolo distinto al de la aplicación. Asegúrate de que el endpoint del health check devuelva 200 dentro del timeout.
¿Cuál es la diferencia entre un 502 y un 504 en el contexto de una CDN? 502 significa que la CDN recibió una respuesta malformada del origen. 504 significa que el origen no respondió dentro del timeout configurado en la CDN. Ambos indican problemas del origen pero requieren correcciones distintas de timeout o validación de respuesta.
¿Cómo depuro errores 5xx intermitentes? Ejecuta el mismo request varias veces y compara las respuestas. Si el 5xx ocurre de forma aleatoria, revisa si hay agotamiento de recursos (connection pools, threads, conexiones de base de datos) o pausas de garbage collection usando herramientas de profiling de aplicación.
¿Qué código de estado debería devolver cuando una dependencia está caída? Devuelve 502 Bad Gateway. No lo enmascares como un 500 o 503. El 502 indica correctamente que el error se originó en una dependencia, no en el servicio mismo.
¿Cómo configuro alertas de monitoreo para códigos de estado? Alerta cuando la tasa de 5xx supere 0.1% en 5 minutos. Alerta cuando la tasa de 4xx supere el 10% del total de requests. Alerta ante caídas repentinas en la tasa de 2xx. Configura alertas separadas para cada endpoint crítico.
¿Cuál es la relación entre los códigos de estado y los SLI? Los códigos de estado son un insumo directo para los SLI de disponibilidad. Cuenta los 5xx y los 4xx apropiados (timeouts) como fallo. Divide las respuestas exitosas entre el total de requests para calcular la disponibilidad. Úsalo para dar seguimiento al cumplimiento del SLO.
Cómo aplica esto en la práctica
En sistemas de producción, un solo código de estado rara vez cuenta toda la historia. El mismo 502 puede significar un timeout del origen, una respuesta inválida del upstream o una mala configuración de la CDN. Rastrear un código de estado a través del sistema importa más que simplemente reconocerlo.
Los equipos que manejan la respuesta a incidentes de forma efectiva mantienen runbooks para cada patrón de código de estado. Estos runbooks especifican qué logs revisar 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 implementarlo en Azion
Azion brinda herramientas para rastrear códigos de estado en toda la ruta del request:
- Edge Logs: exporta logs de requests en tiempo real vía Azion Data Streaming para ver códigos de estado en cada capa
- Application Analytics: usa Azion Metrics para filtrar por clase de código de estado e identificar patrones anómalos
- Configuración de respuesta de error: personaliza las respuestas 4xx y 5xx que devuelve el edge de Azion, incluyendo hints de retry
- Reglas de alerta: configura alertas basadas en umbrales para tasas de 5xx con granularidad por aplicación
Aprende más en la documentación de Azion.
Fuentes:
- IETF. “HTTP Semantics.” RFC 9110. 2022.
- Google SRE. “Service Level Objectives.” 2023.
- HTTP Archive. “Web Almanac.” 2025.
- NIST. “Guide to General Server Security.” SP 800-123.