Clases de Códigos de Estado HTTP – 2xx Códigos de Éxito y 4xx Errores del Cliente
Este artículo es una explicación conceptual sobre las clases de códigos de estado HTTP, incluyendo preguntas de examen y etiquetas.
En Pocas Palabras
- 2xx: procesamiento exitoso (200 OK, 201 Created, 202 Accepted, 204 No Content)
- 4xx: errores causados por el cliente (400, 401, 403, 404, 409, 422, 429)
Descripción Técnica Compacta
2xx señala el procesamiento exitoso de una solicitud, mientras que 4xx marca errores causados por el cliente. 2xx incluye los éxitos típicos: 200 OK para operaciones de lectura, 201 Created con encabezado Location para recursos recién creados, 202 Accepted para operaciones iniciadas de forma asincrónica, 204 No Content cuando no se devuelve cuerpo. 4xx describe errores del cliente: 400 Bad Request para errores de validación, 401 Unauthorized cuando falta la autenticación, 403 Forbidden cuando no hay autorización, 404 Not Found para recursos desconocidos, 409 Conflict para conflictos de versión, 422 Unprocessable Content cuando los datos son semánticamente inválidos, 429 Too Many Requests cuando se alcanza el límite de velocidad.
Puntos Clave Relevantes para Exámenes
- 201 Created siempre con encabezado Location apuntando a la nueva recurso
- 204 No Content solo cuando realmente no se necesita devolver un cuerpo
- 202 Accepted para flujos asincronos con punto final de estado posterior
- Estructura de error consistente con Problem Details e ID de error rastreable
- 409 Conflict en casos de colisión ETag y actualizaciones concurrentes
- 401 para autenticación faltante, 403 para autorización faltante
- Códigos limpios reducen el esfuerzo de soporte y costos de integración
- Describir códigos de estado y objetos de error por operación en OpenAPI
Componentes Principales
- Línea de estado con código y frase de razón
- Códigos 2xx: 200, 201, 202, 204
- Códigos 4xx: 400, 401, 403, 404, 409, 422, 429
- Encabezados: Location, Retry-After, ETag, Content-Type
- Solicitudes condicionales: If-Match, If-None-Match, If-Modified-Since
- Reglas de idempotencia por método
- Objetos de error: Problem Details (type, title, status, detail, instance)
- Paginación en respuestas 200 con enlaces (First, Prev, Next, Last)
- Observabilidad: ID de correlación, Trace-ID, Logging
- Procedimientos de prueba: pruebas negativas, Contract Tests, reintentos y conflictos ETag
Ejemplo Práctico
// Crear un pedido con confirmación posterior
POST https://api.shop.de/orders
Headers: Content-Type: application/json, Idempotency-Key: abc-123
Body: { customerId: 123, items: [{ sku: "A1", qty: 2 }] }
Respuesta con creación inmediata:
Status: 201 Created
Headers: Location: https://api.shop.de/orders/42, ETag: W/"7c9"
Body: { id: 42, status: "created" }
Respuesta con procesamiento asincrónico:
Status: 202 Accepted
Headers: Location: https://api.shop.de/jobs/987, Retry-After: 10
Body: { jobId: 987, state: "queued" }
Conflicto por ETag obsoleto:
PUT https://api.shop.de/orders/42
Headers: If-Match: W/"7c9"
Body: { status: "confirmed" }
El servidor tiene una versión más reciente:
Status: 412 Precondition Failed
Body: application/problem+json
{ type: "https://problems/concurrency", title: "Precondition failed", status: 412, detail: "Version mismatch", instance: "/orders/42" }
Ventajas y Desventajas
Ventajas
- Semántica clara, mejor control del cliente
- Manejo de errores más sencillo
- Mejores estrategias de caché y repetibilidad
- Menor esfuerzo de soporte
Desventajas
- Códigos incorrectos confunden a los clientes
- Dificultan el caché y los reintentos
- Los valores por defecto diferentes del framework conducen a inconsistencias
- Se requiere cuidado adicional en documentación y pruebas
Preguntas Típicas de Examen (con Respuesta Breve)
- ¿Cuándo usar 201 Created y qué encabezados son relevantes? Para crear nuevos recursos, Location apunta a la nueva URI, ETag opcional para actualizaciones posteriores.
- ¿Diferencia entre 200 OK y 204 No Content? 200 transmite la representación, 204 omite el cuerpo; usa 204 solo cuando el cliente no necesita contenidos.
- ¿Flujos asincronos con códigos de estado? 202 Accepted con punto final de estado en el encabezado Location, opcionalmente Retry-After.
- ¿401 vs. 403, cuándo cuál? 401 cuando falta o es inválida la autenticación, 403 cuando el usuario autenticado no tiene permisos.
- ¿409 Conflict en APIs REST? Conflictos de aplicación: conflictos de versión, recursos duplicados, violaciones de reglas de negocio.
- ¿422 en lugar de 400 Bad Request? 422 cuando el JSON es sintácticamente correcto pero semánticamente inválido (violaciones de reglas de dominio).
- ¿ETag e If-Match para actualizaciones seguras? El cliente envía If-Match, el servidor ejecuta la actualización solo si la etiqueta coincide, sino 412.
- ¿Idempotencia con códigos de estado y reintentos? Los métodos idempotentes (PUT, DELETE) permiten reintentos, POST requiere Idempotency-Key.
Continúa en la Ruta de Aprendizaje de APIs
El siguiente artículo en la ruta de aprendizaje de APIs trata sobre HTTP/2 y HTTP/3: Protocolo en Perspectiva — la evolución del protocolo HTTP con Multiplexing, QUIC y rendimiento mejorado.