Skip to main content
A network can lose an answer after the call already ran. Sending that call again could then send a message twice, or pay for an enrichment twice. An 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:
An idempotency key is 1 to 255 visible ASCII characters. Any other value answers 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-Usd is 0.000000, and the retry shows in GET /v1/requests with isReplay true and no cost.
  • The same key with a different request answers 422 idempotency_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 409 idempotency_in_progress. Wait a few seconds, then try again with the same key.
  • Only successful answers are remembered. A refusal, which is any 4xx and a 429 too, frees the key at once: the same key runs the call again, so a corrected retry works.
  • After a 5xx the key is held for 5 minutes from the call’s start, because the call may still take effect. A retry in that time answers 409 idempotency_in_progress; after it, the same key runs the call again.
  • When a send’s outcome cannot be known, the retry answers 409 idempotency_outcome_unknown instead 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.