En la lección anterior fuimos dejando números por el camino: 201 al crear con Location, 204 sin cuerpo, 404 frente a 410, 409 cuando la transición no es posible, 415 cuando el Content-Type no se admite. Cada uno de esos códigos es una decisión de contrato: es lo primero que lee un cliente y lo que determina si reintenta, si muestra un error al usuario, si redirige o si cierra la sesión. Elegir mal el código convierte en indescifrable una API que por lo demás está bien diseñada. Esta lección recorre los códigos que una API REST usa de verdad —no la lista completa del registro de IANA—, construye un árbol de decisión para acertar siempre, y diseña el cuerpo del error de Tienda Aroma, comparándolo con el estándar application/problem+json.

1. Las cinco familias y por qué importan
2. La familia 2xx: éxito
3. La familia 3xx: redirección
4. La familia 4xx: error del cliente
5. La familia 5xx: error del servidor
6. Tabla maestra de Tienda Aroma
7. Árbol de decisión: cómo elegir el código correcto
8. El cuerpo del error: problem+json y el formato de Tienda Aroma
9. Catálogo de códigos de error de negocio
10. Antipatrones

En 01-03 vimos el mapa; ahora entramos en el detalle. La primera cifra del código clasifica la respuesta:

Esta clasificación no es decorativa: es lógica de la que depende software real. Un cliente HTTP genérico, un balanceador o el gateway de un socio deciden basándose solo en la primera cifra. Si devuelves 200 para un error, ningún reintento automático se disparará y ninguna alerta saltará. Si devuelves 500 por un dato mal escrito por el cliente, el sistema reintentará una petición que nunca va a funcionar, y tu equipo de guardia recibirá un aviso a las tres de la mañana por un fallo que no es suyo.

De la familia 1xx solo merece mención 100 Continue, que gestionan los clientes HTTP de forma transparente al subir cuerpos grandes. No la usarás explícitamente.

El éxito genérico, con cuerpo. Lo usan GET, PUT, PATCH correctos y los POST de acción que no crean recurso nuevo.

Recuerda de 02-03: un GET de colección sin resultados es 200 con {"datos": [], "total": 0}, nunca 404.

Se ha creado un recurso. Obligatoria la cabecera Location con su URI.

Location es lo que permite al cliente encadenar sin construir URLs a mano, y es el mínimo de hipermedia que toda API debería cumplir. En Tienda Aroma la devuelven POST /pedidos, POST /cafes, POST /cafes/{id}/resenas, POST /pedidos/{id}/pago y todos los subrecursos de acción.

"He aceptado la petición, pero todavía no la he procesado." Es el código del procesamiento asíncrono, y su contrato incluye decirle al cliente dónde consultar el progreso.

Cuidado con la trampa del 202: cuando devuelves 202 estás diciendo que puede fallar después, así que necesitas un recurso donde el cliente vea el resultado final. Un 202 sin sitio donde mirar es un agujero negro.

Éxito sin cuerpo. El cliente no debe intentar parsear nada. Usos en Tienda Aroma: DELETE correcto, PUT/PATCH cuando el cliente no necesita la representación, y OPTIONS.

Regla estricta: 204 significa cuerpo de longitud cero. Devolver 204 con un JSON dentro rompe clientes que, correctamente, ni leen el flujo.

Respuesta parcial a una petición con Range. En Tienda Aroma aparece exactamente en un sitio: la descarga reanudable de la factura en PDF.

No se usa para paginar JSON: para eso están los mecanismos de 02-06.

El recurso ha cambiado de URI para siempre. Tienda Aroma lo usa para normalizar la barra final (/cafes/ → /cafes) y para las URIs heredadas de la API antigua.

"Lo que tienes en caché sigue valiendo." Responde a peticiones condicionales con If-None-Match o If-Modified-Since, y va sin cuerpo, que es justamente el ahorro.

La caché condicional completa —ETags, Last-Modified, validación, revalidación— se desarrolla en 04-06. Aquí basta con saber que 304 no es un error, sino un éxito muy barato.

El problema histórico: ante un 301 o 302, muchos clientes convertían un POST en un GET al seguir la redirección, cosa que el estándar no pretendía pero que se consolidó como práctica. Para eliminar la ambigüedad se crearon dos códigos que garantizan que el método y el cuerpo se conservan:

Decisión de Tienda Aroma: no se usa 302 en ningún caso. Para lo permanente, 301 si solo afecta a lecturas y 308 si puede afectar a escrituras; para lo temporal, 307.

Es la familia más rica y la que más se equivoca. En todas ellas el cuerpo lleva el formato de error de la sección 8.

La petición está mal formada o los datos no son válidos: JSON con error de sintaxis, tipo incorrecto, campo obligatorio ausente, campo desconocido (recuerda: Tienda Aroma es estricta en la entrada), parámetro de query inválido.

Nota de diseño importante: se devuelven todos los errores de validación a la vez, no el primero. Un formulario que falla campo a campo, en peticiones sucesivas, es una tortura para el usuario.

La distinción que más se equivoca del mundo HTTP. La forma de recordarla:

• 401 = "no sé quién eres". Falta el Authorization, el token es inválido o ha caducado. La respuesta debe incluir WWW-Authenticate. El cliente puede arreglarlo autenticándose.
• 403 = "sé quién eres y no puedes". La identidad es válida, pero le faltan permisos. Volver a autenticarse no sirve de nada.

El nombre 401 Unauthorized es un error histórico del estándar: debería llamarse Unauthenticated. Consecuencia práctica en la SPA de Tienda Aroma: ante 401 intenta refrescar el token y reintentar una vez; ante 403 muestra directamente "no tienes permiso" y no reintenta.

Existe un tercer caso, incómodo pero importante: cuando un cliente autenticado pide un recurso ajeno (GET /v1/pedidos/ped_9999, que es de otra persona), responder 403 confirma que ese pedido existe. Para evitar esa fuga, Tienda Aroma responde 404 en los recursos privados de otros clientes. Es una decisión de seguridad deliberada, se llama enmascaramiento y se trata en 04-02.

410 es más informativo cuando lo sabes con certeza: le dice al cliente que deje de pedirlo. Es especialmente útil en el apagado de versiones antiguas (02-07).

El recurso existe, pero no admite ese método. Obligatoria la cabecera Allow.

Distínguelo de 404: si DELETE /v1/cafes diera 404, el desarrollador buscaría una errata en la URL en vez de darse cuenta de que el método es el equivocado.

Se confunden porque las dos hablan de formatos, pero apuntan en direcciones opuestas:

• 406 → el servidor no puede producir lo que el cliente pide en Accept (salida).
• 415 → el servidor no entiende lo que el cliente envía en Content-Type (entrada).

La petición es válida pero choca con el estado actual del recurso. Es el código de la lógica de negocio, y en Tienda Aroma aparece a menudo:

Otros conflictos del catálogo: pedido_ya_pagado, pedido_ya_anulado, resena_ya_moderada, operacion_en_curso. La regla para distinguirlo de 400: si los datos son correctos y lo que impide la operación es el estado del recurso, es 409.

Falló una condición previa enviada por el cliente, típicamente If-Match con un ETag antiguo. Es el mecanismo de concurrencia optimista que evita la actualización perdida:

Los ETags y las peticiones condicionales se desarrollan en 04-06.

422 (renombrado Unprocessable Content en la RFC 9110) significa: la sintaxis es correcta, entiendo el documento, pero sus contenidos no se pueden procesar. Ejemplo canónico: un JSON perfectamente formado que pide una fecha de entrega en el pasado.

El debate lleva años abierto y estas son las dos posturas:

Decisión de Tienda Aroma: 400 para todos los errores de validación de entrada (sintaxis, tipos, campos obligatorios, enumerados, rangos), con el detalle campo a campo en detalles. 422 se reserva para un caso muy concreto y bien delimitado: la reutilización indebida de una Idempotency-Key con un cuerpo distinto (02-03), donde la petición es impecable pero no se puede procesar por un motivo que no es ni de formato ni de estado del recurso.

Lo importante no es cuál de las dos posturas eliges, sino escribirla en la guía de estilo y no desviarte: lo que rompe a los clientes es que el mismo tipo de fallo devuelva 400 en un endpoint y 422 en otro.

Se ha superado el límite de peticiones. Debe acompañarse de Retry-After y, en Tienda Aroma, de las cabeceras de cuota:

Las políticas, ventanas y algoritmos de limitación son la lección 04-04.

Aquí el cliente no ha hecho nada mal. Regla de oro: nunca filtres detalles internos —trazas de pila, consultas SQL, rutas de fichero, nombres de servidores— porque son información de oro para un atacante.

El cajón de sastre: excepción no controlada. Debe llevar un identificador de traza para que el cliente pueda citarlo al abrir una incidencia:

Ese trazaId es la costura entre la respuesta y tus logs, y es la base de la observabilidad (04-07).

503 es el único que puede planificarse, y por eso lleva Retry-After, que admite segundos o una fecha HTTP:

Precaución con 504: el tiempo de espera se agotó, pero la operación puede haberse ejecutado igualmente aguas arriba. Es exactamente el escenario que justifica las claves de idempotencia de 02-03.

Recorre este árbol para cada endpoint nuevo y tendrás la mitad de la documentación escrita.

El código de estado dice qué categoría de fallo ha ocurrido; el cuerpo dice qué ha pasado exactamente. Sin cuerpo, un 400 obliga al desarrollador a adivinar.

Existe un formato estándar de cuerpo de error, definido originalmente en la RFC 7807 y actualizado por la RFC 9457:

Campos definidos por la norma:

Ventajas: es estándar, hay bibliotecas que lo generan y lo consumen, y el type como URI garantiza unicidad global. Inconvenientes prácticos: los nombres son crípticos para quien no conoce la RFC, type como URL invita a inventar URLs que nadie mantiene, las extensiones al mismo nivel que los campos estándar pueden colisionar, y el Content-Type distinto obliga a los clientes a manejar dos tipos de respuesta.

Decisión de Tienda Aroma: formato propio, por tres razones: (1) el envoltorio error hace imposible confundir una respuesta correcta con una errónea, incluso ignorando el código de estado; (2) detalles como array resuelve de forma natural la validación de formularios, que es el caso más frecuente; (3) mantener application/json en toda la API simplifica los clientes. La decisión se documenta explícitamente junto a la alternativa estándar, y en 02-08 quedará reflejada como esquema reutilizable en OpenAPI.

1. codigo es contrato. En snake_case, estable, único, y nunca se traduce. Es lo que el software compara.
2. mensaje es para humanos. Puede cambiar de redacción y puede traducirse (Accept-Language, 02-05). Nunca lo compares en el código.
3. detalles es un array, siempre presente aunque esté vacío, para que los clientes no tengan que comprobar si existe.
4. Nada de datos sensibles: ni consultas, ni trazas de pila, ni si un correo existe en la base de datos.
5. Los 5xx llevan trazaId; los 4xx no lo necesitan.

La implementación de todo esto como middleware de Express es la lección 03-07; aquí solo hemos fijado el contrato.

El catálogo forma parte del contrato tanto como las URIs. Este es el inicial de Tienda Aroma:

Convención de nombres: <entidad>_<problema> para lo específico (cafe_no_encontrado) y <problema> a secas para lo transversal (datos_invalidos). El catálogo solo crece: retirar un código es un cambio rompedor (02-07).

Es el antipatrón más extendido y el más dañino. Consecuencias: los clientes HTTP no detectan el error, los reintentos automáticos no se disparan, la monitorización marca 100 % de éxito, los proxys cachean el error como si fuera una respuesta buena, y cada consumidor tiene que inventarse su propia lógica de detección. Renuncia por completo al nivel 2 de Richardson.

Si un POST /v1/cafes con precioEuros: "gratis" provoca 500, el sistema del cliente reintentará una petición condenada al fracaso y tu equipo recibirá una alerta por un fallo ajeno. Regla: si la petición no puede funcionar tal cual, es 4xx.

299 Casi OK, 450 Error de negocio, 600 Fallo. Los intermediarios interpretan los códigos desconocidos por su primera cifra en el mejor de los casos, y los rechazan en el peor. Usa solo códigos registrados; para el detalle de negocio ya tienes el campo codigo del cuerpo.

• 404 para todo error del cliente, escondiendo 400, 403 y 409 bajo el mismo número.
• 401 cuando faltan permisos: manda al usuario a autenticarse otra vez, no sirve de nada y a menudo provoca bucles de refresco de token.
• Mensajes inútiles: "Error", "Algo ha fallado", "Consulta el log".
• Filtrar la traza de pila en producción.
• Cuerpo en un 204: hay clientes que no leen el flujo y lo dejarán a medias.

• Confundir 401 y 403. No sé quién eres frente a sé quién eres y no puedes. Memorízalo así.
• Olvidar Location en un 201. El cliente se queda sin la URI del recurso creado.
• Olvidar Allow en un 405 o WWW-Authenticate en un 401: son obligatorias por norma y hay clientes que dependen de ellas.
• Usar 409 para errores de validación. 409 es del estado del recurso; los datos malos son 400.
• Devolver 200 con lista vacía… en un elemento. La colección vacía es 200; el elemento inexistente es 404.
• Cambiar el código de un endpoint ya publicado. Pasar de 200 a 204 rompe clientes que leen el cuerpo: es un cambio rompedor (02-07).
• Consejo: escribe la tabla de códigos de cada endpoint antes de implementarlo. Es una columna obligatoria de la documentación de referencia (02-08).
• Consejo: comprueba tus errores con curl -i. Ver la respuesta cruda descubre Content-Type mal puestos y cuerpos vacíos que un cliente elegante te oculta.

Indica el código de estado, el codigo de error y las cabeceras relevantes de cada situación:

1. POST /v1/cafes sin cabecera Authorization.
2. POST /v1/resenas/res_101/aprobacion con el token de un cliente normal.
3. POST /v1/pedidos con 100 unidades de caf_002, que tiene stock 80.
4. GET /v1/cafes/caf_999.
5. PUT /v1/pedidos/ped_5001 (Tienda Aroma solo admite PATCH ahí).
6. POST /v1/pedidos/ped_5001/pago sobre un pedido ya pagado.
7. PATCH /v1/cafes/caf_001 con Content-Type: application/xml.
8. POST /v1/cafes con {"nombre": "", "precioEuros": -3}.
9. DELETE /v1/carritos/car_77/lineas/caf_002, correcto.
10. El servicio interno de stock no responde en 5 segundos.

Una API heredada responde así. Reescribe cada respuesta con el código, las cabeceras y el cuerpo correctos según el contrato de Tienda Aroma.

Traduce este error de Tienda Aroma al formato application/problem+json de la RFC 9457, y explica qué se gana y qué se pierde en la traducción:

Solución 1

Solución 2

Aquí había dos fallos: el código (un error de validación es del cliente, 400, no 500) y la fuga de la traza de pila con rutas internas del servidor.

El mensaje "debes iniciar sesión" delata que el problema es de autenticación, así que el código correcto es 401, no 403, y falta la cabecera WWW-Authenticate.

Solución 3

Se gana: un formato estándar que herramientas y bibliotecas reconocen sin configuración; un type como URI globalmente única que además puede ser un enlace a la documentación del error; y instance, que identifica la ocurrencia concreta y ayuda a correlacionar con los logs.

Se pierde: el envoltorio error, que permitía distinguir de un vistazo una respuesta correcta de una errónea sin mirar el código; la homogeneidad del Content-Type en toda la API; y la nitidez de los nombres —codigo/mensaje/detalles son más directos para el consumidor que type/title/detail—. Además, la lista de errores de validación (errores) es una extensión propia en ambos casos: la RFC no la estandariza, así que esa parte hay que documentarla igual.

Los códigos de estado son la primera línea del contrato: dicen si la operación fue bien, de quién es el problema y si tiene sentido reintentar. Ahora sabes cuándo devolver 201 con Location y cuándo 204 sin cuerpo, distinguir 401 de 403 y 404 de 410, reservar 409 para los conflictos de estado como el stock_insuficiente, no confundir 406 con 415, y acompañar los 5xx de Retry-After y de un trazaId sin filtrar nada interno. Tienes además un árbol de decisión reutilizable, el catálogo de códigos de error de negocio de Tienda Aroma y una postura razonada frente a application/problem+json. Y sabes qué no hacer: 200 con exito: false, 500 por datos mal escritos por el cliente y códigos inventados.

Hasta aquí hemos diseñado el sobre: dónde va la petición, con qué verbo y con qué resultado. Falta el contenido. En la lección siguiente, 02-05 Representaciones, cabeceras y negociación de contenido, diseñaremos el cuerpo de las respuestas de Tienda Aroma: nombres y tipos de campo, fechas, importes monetarios, nulos frente a ausentes, el envoltorio datos/total, cuándo incrustar y cuándo enlazar con _links, la expansión y la selección de campos, y toda la negociación de contenido con Accept, Content-Type, Accept-Language y Accept-Encoding, incluida la factura en PDF y la subida de imágenes de café.