Idempotency
Concepts
Idempotency
How to retry bookings without duplicates using the Idempotency-Key header.
POST /bookings requires the Idempotency-Key header: a unique value for each booking you try to make (a UUID v4 works). If the network fails and you don't know whether the booking was created, retry with the same key and body.
| Retry | Result |
|---|---|
| Same key, same body | The stored response from the first time (same HTTP status and body). No second booking. |
| Same key, different body | 409 with idempotency_conflict. Use a new key for a different booking. |
| No key | 400 with idempotency_key_required. |
Idempotency keys are scoped to the API key. Save yours with your order before calling Muvon:
js
// One key per booking attempt, saved with your order before calling Muvon
const idempotencyKey = order.muvonIdempotencyKey ?? (order.muvonIdempotencyKey = crypto.randomUUID());
await saveOrder(order);
const res = await fetch("https://api.muvon.mx/api/v1/bookings", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MUVON_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(bookingRequest),
});
// On a timeout or a 5xx, send exactly the same request with the same key:
// you get the booking that was already made instead of a second one.Quoting, retrieving and listing change nothing, so they can be retried freely.