Skip to main content
A request that times out tells you nothing about whether it landed. Retrying risks a second company. Not retrying risks none. An idempotency key removes the dilemma: send the same key again and you are answered with the original response instead of the operation running twice.

​
Sending a key

Put a unique value in the Idempotency-Key header on any POST, PUT or DELETE. A UUID is the usual choice. Generate it before the first attempt and reuse the same value for every retry of that one operation.
Request
GET requests need no key. They are already repeatable, and sending one has no effect.

​
What a replay looks like

The replayed response is byte-identical to the first one, status included, and carries one extra header so your integration can tell the two apart:
​
boolean
Present and true only on a replay. Absent on the request that did the work.
That means a 201 Created retried under the same key comes back as 201, with the same resource id, not a 200, and not a second resource.

​
What a key is bound to

A key stands for one operation, and the operation is identified by the method, path, request body and Clemta-Version taken together. Sending the same key with any of those changed is a client bug, so it is refused rather than answered with a response to a different question.
​
409
The key was already used for a different request. Use a fresh key.
​
409
An earlier request with this key is still running, so there is no response to replay yet. Retry the same request with the same key after a short pause.
Keys are scoped to your account, so they never collide with another partner’s.

​
What is remembered, and for how long

Keys are remembered for 24 hours, which covers any retry a client or its queue would still be making. After that the same key is treated as new. Both successes and rejections are settled outcomes and are replayed: retrying a 400 under the same key returns the same 400. A 5xx is not a settled outcome. The key is released, so a retry runs the request again, which is exactly what a retry is for.
1

Generate the key once, per operation

Mint it where you decide to do the work, not where you send the request. A key generated inside the retry loop defeats the whole mechanism.
2

Persist it alongside the work

If your process restarts mid-retry, the key has to survive with it, otherwise the resumed attempt is a new operation as far as the API is concerned.
3

Retry on timeouts, connection errors and 5xx

These are precisely the cases where the outcome is unknown. Back off exponentially, and keep the key.
4

Never reuse a key for a different operation

Two companies means two keys. Reuse is answered with idempotency_key_mismatch, not with a quiet success.