Concepts

Idempotency (safe retries)

Send an Idempotency-Key with every create, so a retried request never makes a second order or booking.

Networks fail. Every request that creates something (POST /v1/orders, POST /v1/reservations) needs an Idempotency-Key header — any unique string of 8–128 characters, e.g. a UUID made when the customer taps “Place order”.

Send the same key when you retry → you get the same order back (with Idempotent-Replayed: true). Never a duplicate.
Same key with a different body → IDEMPOTENCY_KEY_REUSED.
Keys are remembered for 24 hours.
Temporary refusals (CLOSED, NOT_ACCEPTING, PRICE_CHANGED, RATE_LIMITED, 5xx) are not remembered — fix and retry with the same key.

Retry safely

const idempotencyKey = crypto.randomUUID(); // once per checkout
for (let attempt = 0; attempt < 3; attempt++) {
  const res = await fetch('https://api.billzova.com/v1/orders', {
    method: 'POST',
    headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify(order),
  }).catch(() => null);
  if (res && res.status < 500) return res.json();
  await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
}