Idempotency-Key for safe retries

Add an Idempotency-Key header to writes so a retry never creates a duplicate.

On this page

If your connection drops after you send a write, you may not know whether it worked. An Idempotency-Key lets you send it again safely.

When to use it

Add it to any request that adds or changes data (POST, PUT, PATCH, DELETE). Reads do not need it.

Pick a unique string for each real action. It can be 1 to 100 visible characters. For example, your own order number.
Send it as a header: Idempotency-Key: order-1001-lead.
If the call fails in the network, send the exact same request again with the same key.
If the first call worked, you get the first answer again, with a header Idempotent-Replay: true.

Situation	Result
First use of the key	The request runs and its answer is saved.
Same key, same request	The saved answer is replayed.
Same key, different request	422 `idempotency_key_reused`.
Same key while the first is still running	409 `idempotency_in_progress`. Wait and retry.
Key has bad characters or is too long	400 `invalid_idempotency_key`.

Two requests are the same when the method, route and body match.

Only successful answers (200 to 299) are saved. If the first try fails, the key is released, so a fixed retry can run again.

Saved keys are removed after about 24 hours (daily housekeeping). Keys are kept separately per access key.

Customers and leads are also protected by matching. A person with the same email or phone is never added twice. Idempotency adds protection for other fields and for repeat responses.
Generate the key before sending, not after.
Do not reuse the same key for a different record.

Tell us what you were trying to do and a person will reply.