Idempotencia

POST /bookings requiere un header Idempotency-Key. Es la única operación
que lo hace, porque es la única que crea algo que un huésped pagó.

Idempotency-Key: booking-2027-03-01-ada-01

Por qué es obligatorio y no opcional

Un timeout de red no dice nada sobre si la reserva se creó. La petición pudo
haber sido recibida, procesada y confirmada mientras la respuesta se perdía de
vuelta. Reintentar a ciegas crea una segunda reserva para el mismo huésped en la
misma habitación — que el hotel después tiene que notar y deshacer a mano.

Con una key, el reintento es seguro: repetir la misma key con el mismo cuerpo
devuelve la reserva original, con el mismo 201, en vez de crear una
segunda.

Elegir una key

Hay que escoger un valor único por intento de reserva y que uno pueda
reproducir al reintentar. Algo derivado de la propia intención de reserva
funciona bien — un id de carrito, un id de sesión más la estadía, un UUID
generado y guardado antes de mandar.

Lo que no funciona es un valor que se regenere en cada intento. Un UUID nuevo por
reintento es lo mismo que no tener key.

Las tres fallas

Falta el header — 422:

{
  "message": "The Idempotency-Key header is required on this endpoint.",
  "error_code": "IDEMPOTENCY_KEY_REQUIRED"
}

Reusada con otro cuerpo — 409:

{
  "message": "This Idempotency-Key was already used with a different request body.",
  "error_code": "IDEMPOTENCY_KEY_REUSED"
}

Esta es la interesante. Significa que la key no es tan única como uno creía — dos
reservas distintas la están compartiendo. Es un bug de quien llama, y reintentar
no lo va a arreglar.

Todavía en vuelo — 409:

{
  "message": "A request with this Idempotency-Key is still in flight.",
  "error_code": "IDEMPOTENCY_IN_FLIGHT"
}

El primer intento no ha terminado. Hay que esperar y reintentar con la misma key;
no empezar una nueva.

El patrón que funciona

1. Generar y persistir una key antes de mandar.
2. Mandar. Ante un timeout, un error de conexión o un 5xx, reenviar la misma
   key con el mismo cuerpo.
3. Ante 409 IDEMPOTENCY_IN_FLIGHT, esperar y reenviar la misma key.
4. Ante 409 IDEMPOTENCY_KEY_REUSED, parar y arreglar a quien llama.

Cotizar y después reservar

POST /quote toma el mismo cuerpo que
POST /bookings, menos el huésped, y no reserva nada. Sirve para mostrar un
precio.

Los precios se pueden mover entre las dos llamadas, y el que cuenta es el total
de la propia reserva. Una cotización no es una retención.

Relacionado

• Reservas — lo que se crea.
• Errores — los códigos de arriba junto al resto.