Idempotency-Key
Was ist Idempotency-Key?
Dieser Eintrag liegt derzeit nur auf Englisch vor.
An Idempotency-Key is the deduplication-header contract Orbit enforces on POST endpoints that create resources — messages, calls, contacts, campaigns, and top-ups. Every Orbit SDK auto-generates a UUIDv4 key per request; when you supply your own, Orbit stores it for 24 hours, and a retry with the same key and the same body returns the cached response instead of a duplicate creation or charge.
More detail
The contract has three failure shapes, all in /reference/error-codes: omitting the header where a key is mandatory returns 400 IDEMPOTENCY_KEY_REQUIRED; a key that fails shape validation (8–255 characters, no whitespace padding) returns 400 INVALID_IDEMPOTENCY_KEY; and replaying the same key with a different request body returns 409 IDEMPOTENCY_KEY_REUSED — Orbit refuses the ambiguous replay loudly instead of guessing which request you meant. Within the 24-hour window, same key + same body returns the original response; after the window the entry expires and the key is treated as fresh.
Supplying your own key matters when a retry can leave the process: an SDK crash, a redeployed worker, or a queue re-drive re-mints an auto-generated key on its next attempt, while a stable key you minted — an order id, a campaign run id, a natural identifier — still deduplicates. This is distinct from the SDK's internal retry: that backoff reuses the same auto-generated key inside one process and never duplicates a create, but it cannot survive a process boundary. Money-moving endpoints like POST /balance/top-up make the header mandatory; everywhere else it is optional because the SDK already sends one for you.
Häufige Fragen
- Do I always need to send the Idempotency-Key header myself?
- No — every Orbit SDK auto-generates a UUIDv4 Idempotency-Key on every non-GET request, so plain API usage is already safe. On money-moving endpoints the header is mandatory (400 IDEMPOTENCY_KEY_REQUIRED when omitted), and you should supply your own stable key whenever a retry can leave the process, so a re-driven job still deduplicates.
- What if the same key lands on different request bodies?
- Orbit returns 409 IDEMPOTENCY_KEY_REUSED and creates nothing. Reusing a key against different arguments is a client bug, so Orbit refuses the ambiguous replay loudly instead of guessing which request was meant — mint a fresh key for the genuinely different request and reuse a key only for byte-identical retries within the 24-hour window.
- Does the SDK's built-in retry do this for me?
- Yes, inside one process: the SDK's backoff reuses its auto-generated key, so same-process retries never duplicate a create. The SDK retry cannot survive a crash or redeploy, though — for cross-process dedup you supply your own Idempotency-Key and Orbit stores it for 24 hours against the completed response.
See also
Build it on Orbit
Voice, messaging, email, video, and AI agents on one platform and one pay-as-you-go bill. Start free — no credit card required.