Every write (POST, PUT, PATCH, DELETE) requires an Idempotency-Key
header — in both production and sandbox. It makes retries safe: a network
timeout on POST /bookings can be retried without double-booking.
Idempotency-Key: 3f1c6b90-8e2a-4d77-b5c4-9a0e1f2d3c4b
- UUID v4, unique per logical operation (one per booking attempt, not one per process).
- Retained 24 hours. After that the key is forgotten and a reuse is treated as a new operation.
Semantics
| Situation | Result |
|---|
| Same key, same body | The original response is replayed. No second operation. |
| Same key, different body | 409 idempotency.key.conflict. No action performed. |
| New key | Processed normally. |
Generate the key before the first attempt and reuse the same key for every
retry of that operation. Generating a fresh key per retry defeats the protection.
Recommended retry pattern
- Mint one
Idempotency-Key for the operation.
- Send the request. On
2xx/4xx (except 429), you have a definitive answer — stop.
- On timeout,
5xx, or 429, retry with the same key after a backoff.
- A replayed success returns the original body — safe to treat as success.
Idempotency is independent from request signing:
sandbox sk_test_* keys skip the signature but still require Idempotency-Key. 
