Idempotency-Key header makes the retry safe: the call runs once, and every retry with the same key gets the first call’s answer.
Send a key
Make a new idempotency key for each operation, such as a UUID, and send it with the first try and with every retry:422 validation_failed, with param set to Idempotency-Key.
Calls that take a key
These calls, which send something or charge for it, take one:
Every other route ignores the header.
How an idempotency key works
- It belongs to your organization and the route. A retry sent with another of your API keys is still the same call, and the same idempotency key sent to another route is a different one.
- It is remembered for 24 hours from its first call.
- The same key with the same request answers the first call’s answer again, with the header
Idempotent-Replayed: true. Nothing is sent or charged again:X-Charged-Usdis0.000000, and the retry shows inGET /v1/requestswithisReplaytrue and no cost. - The same key with a different request answers
422idempotency_key_reused. The request is the path, ids included, and the body: the key that launched one campaign cannot launch another. Make a new key for a new operation. A mailbox’s password is the one thing not compared. - A batch or a list enrichment answers its job as it was when it started. Read where the job is now with
GET /v1/jobs/{jobId}. - While the first call is still running, the same key answers
409idempotency_in_progress. Wait a few seconds, then try again with the same key. - Only successful answers are remembered. A refusal, which is any
4xxand a429too, frees the key at once: the same key runs the call again, so a corrected retry works. - After a
5xxthe key is held for 5 minutes from the call’s start, because the call may still take effect. A retry in that time answers409idempotency_in_progress; after it, the same key runs the call again. - When a send’s outcome cannot be known, the retry answers
409idempotency_outcome_unknowninstead of sending again: the first try of a message, a reply, an invitation or an import failed after it may already have gone out. Check whether it did, then use a new key if it did not.
Retry a call
1
Make the idempotency key before the first try
Keep it with the operation, so a retry after a crash or a restart sends the same one.
2
Send the call
A
2xx is final: the same key answers it again for 24 hours.3
On a timeout, a 5xx or a 429, send it again
Send the same body with the same key. After a
429, wait the seconds in Retry-After first; after a 5xx or a timeout, back off for a few seconds more each time, and keep the same key while the answer is 409 idempotency_in_progress. An answer that carries Idempotent-Replayed: true is the first call’s: nothing ran twice. On 409 idempotency_outcome_unknown, stop retrying and check what was sent.