Códigos de estado HTTP: semántica y patrones de arquitectura

Los códigos de estado HTTP son códigos de respuesta de tres dígitos definidos en RFC 9110 que codifican el resultado del procesamiento de una solicitud. A nivel de protocolo, son señales legibles por máquina que intermediarios y clientes usan para determinar el comportamiento de caché, la elegibilidad para reintento y el ciclo de vida de la conexión sin inspeccionar el cuerpo de la respuesta.

Cómo funcionan los códigos de estado a nivel de protocolo

El rol de los códigos de estado en la semántica HTTP

Los códigos de estado ocupan la primera línea de una respuesta HTTP y no tienen opcionalidad — toda respuesta debe incluir uno. Están divididos en cinco clases por el primer dígito, cada una definiendo una categoría principal de semántica de respuesta. Los dos últimos dígitos proporcionan granularidad dentro de la clase pero no tienen significado estructural.

HTTP/1.1 200 OK\r\n
          ││ └── Frase de razón (informativa, sin función semántica)
          │└──┴── Código específico dentro de la clase
          └── Clase (2 = éxito)

La frase de razón (“OK”, “Not Found”) no tiene función a nivel de protocolo. Los clientes DEBEN ignorarla para la toma de decisiones. Solo el código numérico es autoritativo.

Códigos de estado y la clave de caché HTTP

Los códigos de estado determinan el comportamiento de caché a través de la cabecera Cache-Control y la capacidad de caché inherente al código. RFC 9111 define la siguiente capacidad de caché predeterminada:

Extensibilidad de códigos de estado

RFC 9110 reserva todo el rango 1xx-5xx pero no restringe el registro de nuevos códigos dentro de esas clases. El IANA HTTP Status Code Registry gestiona el conjunto oficial. Los códigos personalizados siguen reglas semánticas:

• Los códigos 1xx son informativos (respuesta final aún no disponible)
• Los códigos 2xx indican éxito
• Los códigos 3xx requieren acción del cliente para completar la solicitud
• Los códigos 4xx indican error del cliente
• Los códigos 5xx indican error del servidor

Códigos de estado como señales de protocolo

Señales de ciclo de vida de la conexión

• 101 Switching Protocols: Actualiza conexión de HTTP a un protocolo diferente (WebSocket, HTTP/2). Después de esta respuesta, la conexión HTTP es reemplazada.
• 408 Request Timeout: El servidor cierra conexiones ociosas. El cliente debe reintentar en una nueva conexión.
• 421 Misdirected Request: La solicitud fue enviada a un servidor que no puede responder. El cliente debe intentar en una conexión u host diferente.

Semántica de reintento

Los clientes NO DEBEN reintentar automáticamente en 400, 401, 403, 404 o 405. Estos indican una condición del lado del cliente que no cambiará con la repetición.

Arquitectura avanzada de troubleshooting

Rastreando códigos de estado a través de la ruta de la solicitud

En sistemas distribuidos, un código de estado se modifica en cada capa. Entender qué capa generó el código es necesario:

Solicitud del Cliente
  │
  ▼
Capa Edge/CDN (genera 403 para WAF, 502/504 para problemas de origen)
  │
  ▼
Balanceador de Carga (genera 503 para upstream sin instancias saludables)
  │
  ▼
API Gateway (mapea errores downstream, genera 502)
  │
  ▼
Aplicación (genera 200/4xx/5xx)
  │
  ▼
Dependencias Upstream (generan errores que propagan)

El código de estado que el cliente ve es el ÚLTIMO código generado a lo largo de esta ruta. Para encontrar la causa raíz, debe inspeccionar logs en cada capa.

Patrones de propagación de error

Patrones de arquitectura de códigos de estado

Esquema uniforme de error

Las respuestas de error deben seguir un esquema consistente para que los clientes las interpreten de manera uniforme:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "id": "req_abc123",
    "detail": "El campo 'email' debe ser una dirección de correo electrónico válida",
    "source": {
      "pointer": "/data/attributes/email"
    }
  }
}

Este patrón, basado en RFC 9457 (Problem Details for HTTP APIs), separa el componente legible por máquina (código de estado) de los componentes legibles por humanos y accionables por máquina en el cuerpo.

Mapeo de códigos de estado entre protocolos

Mapeo gRPC a HTTP:

Métricas y Medición

• Error budget de código de estado: Tasa máxima de 5xx permitida en una ventana continua (SLO típico: 99,9% de disponibilidad = 0,1% de budget 5xx)
• Tiempo medio para acknowledgment (MTTA): Tiempo desde la alerta 5xx hasta el acknowledgment del ingeniero (meta: <15 minutos para P1)
• Tiempo medio para resolución (MTTR): Tiempo desde la alerta hasta la normalización de la tasa de error (meta: <60 minutos para P1)

Referencias del sector:

• 99,9% de disponibilidad permite 8,76 horas de downtime por año (Google SRE)
• 99,99% de disponibilidad permite 52,56 minutos de downtime por año (Google SRE)
• Principales causas de errores 5xx: bugs de despliegue (40%), fallos de dependencia (30%), cambios de configuración (20%), agotamiento de capacidad (10%) (Catchpoint, 2025)

Errores Comunes y Correcciones

Error: Devolver 200 OK para todas las respuestas y poner información de error solo en el cuerpo Corrección: Siempre devuelva la clase de código de estado correcta. Los proxies, CDN y herramientas de monitoreo leen el código de estado, no el cuerpo. Los códigos de estado incorrectos rompen el caché, las alertas y la lógica de reintento.

Error: Usar 403 cuando 401 es lo correcto Corrección: 401 indica que el cliente no está autenticado. 403 indica que el cliente está autenticado pero no tiene autorización. Usar 403 para ambos impide que los clientes sepan si necesitan reautenticarse o solicitar permisos diferentes.

Error: No implementar la cabecera Retry-After para 429 y 503 Corrección: Incluya Retry-After en segundos o formato de fecha HTTP. Sin ella, los clientes usan retrasos de reintento específicos de la implementación, causando frecuentemente tormentas de reintento.

Error: Almacenar en caché respuestas 4xx sin opt-in explícito Corrección: Por defecto, los CDN y proxies no deben cachear respuestas 4xx. Si se desea caché (ej: 410 Gone), defina Cache-Control explícitamente.

Error: Ignorar la diferencia entre 502 y 503 en el monitoreo Corrección: 502 indica fallo de dependencia upstream. 503 indica un problema de capacidad o disponibilidad local. Cada uno dispara un camino de respuesta a incidentes diferente.

Casos de uso avanzados

Propagación de error en microservicios

En una arquitectura de microservicios, un solo 500 de un servicio upstream puede causar cascada. Implemente el siguiente patrón:

1. Todos los errores downstream se registran con correlation IDs
2. El error upstream se mapea a un 502 para el cliente
3. Los circuit breakers previenen fallos en cascada devolviendo 503 inmediatamente cuando se exceden los umbrales de error
4. Las respuestas de fallback (200 con datos obsoletos) son preferidas a 502 para endpoints de lectura cuando sea aceptable

Manejo de error en GraphQL

GraphQL se desvía del uso estándar de códigos de estado HTTP. Una sola consulta puede fallar parcialmente y tener éxito parcialmente:

{
  "data": {
    "user": null,
    "posts": [...]
  },
  "errors": [
    {
      "message": "Usuario no encontrado",
      "locations": [{"line": 2, "column": 3}],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "status": 404
      }
    }
  ]
}

Los endpoints GraphQL típicamente devuelven 200 incluso cuando ocurren errores, con detalles en el array errors. Algunas implementaciones devuelven 400 para problemas a nivel de solicitud. Esta es una elección de diseño deliberada que sacrifica la semántica HTTP por la capacidad de respuesta parcial.

Entrega de Webhooks

La entrega de webhooks usa códigos de estado de manera diferente. El sistema de entrega espera 2xx para confirmar recepción. Cualquier non-2xx dispara reintentos con backoff exponencial:

• 200: Entregado exitosamente
• 202: Recibido, procesando asincrónicamente
• 400-499: Mala configuración del cliente — el webhook puede ser deshabilitado después de fallos repetidos
• 500-599: Error del servidor — reintentará con backoff

Preguntas Frecuentes

¿Cuál es la relación entre los códigos de estado HTTP y TCP/IP? Los códigos de estado HTTP son un concepto de la capa de aplicación. No tienen relación directa con TCP/IP. Una conexión TCP exitosa no garantiza una respuesta HTTP exitosa, y un reset TCP no produce un código de estado HTTP (el cliente ve código de estado 0).

¿Puedo definir códigos de estado HTTP personalizados? Sí, cualquier código en el rango 1xx-5xx puede usarse, pero debe seguir las reglas semánticas de su clase. Los códigos personalizados deben registrarse en IANA para APIs públicas. Para APIs internas, cualquier código dentro de la clase correcta funciona, pero los clientes pueden no manejar códigos no estándar correctamente.

¿Cómo afectan HTTP/2 y HTTP/3 a los códigos de estado? HTTP/2 y HTTP/3 llevan los mismos códigos de estado que HTTP/1.1. El código de estado permanece igual. La diferencia está en la semántica de la conexión: HTTP/2 multiplexa múltiples streams sobre una sola conexión, por lo que un 408 en un stream no afecta a otros. HTTP/3 usa QUIC, por lo que los resets de conexión no requieren renegociación TCP.

¿Por qué mi API GraphQL devuelve 200 para consultas fallidas? Los endpoints GraphQL devuelven 200 por convención porque el transporte HTTP en sí fue exitoso. Los errores se reportan en el array errors del cuerpo de la respuesta. Esto permite éxito parcial: un campo puede fallar mientras otros devuelven datos.

¿Qué sucede si un CDN recibe un código de estado no estándar? El CDN lo trata según su clase. Un 4xx no estándar será tratado como error del cliente, no cacheado por defecto, y pasado al cliente. Un 2xx no estándar será cacheado según Cache-Control. El valor específico del código importa menos que la clase para el comportamiento del CDN.

¿Cómo manejar códigos de estado en el patrón BFF (Backend for Frontend)? El BFF debe agregar códigos de estado downstream y devolver un único estado coherente al frontend. Mapee múltiples errores downstream al código aplicable más específico. Siempre registre los códigos downstream originales junto con la respuesta del BFF para depuración.

¿Cuál es el código de estado correcto para limitación de tasa por usuario vs por IP? 429 Too Many Requests es correcto para ambos. El cuerpo de la respuesta debe diferenciar entre límites a nivel de usuario y de IP. Use cabeceras como X-RateLimit-Limit y X-RateLimit-Remaining para información de alcance.

¿Cómo interactúan los códigos de estado con HTTP pipelining? HTTP pipelining (HTTP/1.1) permite múltiples solicitudes sin esperar respuestas. Los códigos de estado para respuestas en pipeline DEBEN devolverse en orden. Una respuesta fallida no invalida respuestas subsiguientes en el pipeline. HTTP/2 y HTTP/3 eliminaron la necesidad de pipelining con multiplexación.

¿Debo devolver 404 o 403 para recursos no divulgados? Devuelva 404. Un 403 confirma que el recurso existe pero el acceso es denegado. Un 404 no revela nada sobre la existencia del recurso. Para recursos sensibles a la seguridad (IDs de usuario, rutas de archivo), 404 previene divulgación de información.

¿Cuál es el enfoque correcto para el versionado de códigos de estado en APIs? La semántica de los códigos de estado no debe cambiar entre versiones de API. Si una respuesta transiciona de 200 a 201 o 200 a 202, documéntelo como un cambio crítico. Los códigos de estado son parte del contrato de la API. Use una nueva versión de endpoint si el comportamiento del código de estado debe cambiar.

Cómo se aplica en la práctica

La gestión avanzada de códigos de estado HTTP los trata como señales de protocolo de primera clase, no como etiquetas de error. Cada código lleva semántica específica sobre capacidad de caché, seguridad de reintento y ciclo de vida de la conexión de la que dependen los intermediarios y clientes.

Las organizaciones que ejecutan microservicios a escala implementan esquemas de error estandarizados (RFC 9457), circuit breakers con salida de código de estado apropiada y propagación de correlation ID a través de todas las capas. Los códigos de estado se convierten en entradas para respuesta automatizada a incidentes: un pico de 502 dispara verificaciones de salud de dependencias, mientras que un pico de 503 dispara auto-scaling de capacidad.

Cómo implementar en Azion

Azion proporciona control a nivel de protocolo sobre el manejo de códigos de estado a través de toda la ruta de la solicitud:

1. Respuestas de Error Personalizadas: Configure comportamientos de respuesta por código de estado en el borde, incluyendo cabeceras personalizadas (Retry-After, Cache-Control) y cuerpo
2. Functions: Intercepte y modifique códigos de estado programáticamente usando JavaScript o Rust en el borde antes de que lleguen al cliente
3. Métricas en Tiempo Real: Monitoree distribuciones de código de estado por aplicación, nodo de borde y origen con granularidad de sub-segundos
4. Data Streaming: Exporte metadatos completos de solicitudes incluyendo códigos de estado, tiempos y estado upstream para análisis avanzados
5. Caché Inteligente: Configure políticas de caché basadas en clases de código de estado para prevenir caché de respuestas de error

Más información en la Documentación de Azion.

Recursos Relacionados

• RFC 9457 — Problem Details for HTTP APIs

Fuentes:

• IETF. “HTTP Semantics.” RFC 9110. 2022.
• IETF. “HTTP Caching.” RFC 9111. 2022.
• IETF. “Problem Details for HTTP APIs.” RFC 9457. 2023.
• IANA. “HTTP Status Code Registry.” 2026.
• Google SRE. “Service Level Objectives.” 2023.
• Catchpoint. “Root Cause Analysis of 5xx Errors.” 2025.