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.
- UUID v4, unique per logical operation (one per booking attempt, not one per process).
- 255 characters maximum. A longer key is rejected with
400 idempotency.key.too.long.
- Retained 24 hours. After that the key is forgotten and a reuse is treated as a new operation.
Semantics
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. 
