Idempotency-Key header. If you send the same key with the same
body again, Zquence returns the account it already created instead of creating a second one.
Which endpoints support it?
Other endpoints ignore the
Idempotency-Key header.
How it works
1
Build a key from your business event
Use something that stays the same for every retry of the same operation, for example
crm-case-10482-open. A UUID also works if you store it before the first attempt.
Keys must be 8–255 visible ASCII characters with no spaces.2
Send it as a header
3
Retry with the same key and body
If the request times out or returns
429 or 5xx, send it again unchanged.Behavior guarantees
- Keys are scoped to the API key and its environment. The same string on a different key never collides.
- Keys don’t expire. A key stays tied to the account it created.
- A replay returns
201 Createdwith the account’s current state. No second account, emails, or webhooks. - Reusing a key with a different body returns
409with codeidempotency_key_reused. - Two bodies count as the same after trimming whitespace, lowercasing
accountType, and ignoring participant order. - A request that fails validation (
400) stores nothing, so you can fix the body and reuse the key.
Example
What to key on
The key should come from the business event, so every retry of that event produces the same key.
Pair it with
externalReference for a second guarantee: even with a new key, Zquence rejects a
second account for the same reference with 409 external_reference_exists.