Skip to main content
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.
  1. Mint one Idempotency-Key for the operation.
  2. Send the request. On 2xx/4xx (except 429), you have a definitive answer — stop.
  3. On timeout, 5xx, or 429, retry with the same key after a backoff.
  4. 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.