Idempotency & retries
When a request times out you cannot tell whether it reached us. Retry it — with the same Idempotency-Key, so a second copy cannot act twice.
Idempotency-Key
Every POST accepts an Idempotency-Key header: any unique string of 1–255 printable ASCII characters, for example a UUID you generate per operation and store with it, so a retry sends the same value. Anything else → 400 invalid_field.
| Retry with the same key | Answer |
|---|---|
| Same request, first one finished | The stored first answer — same status, same body byte for byte, same ETag and Location — with Idempotent-Replayed: true. Nothing runs again. |
| Same request, first one still running | 409 idempotency_in_progress — wait a second and retry. |
| Different path or body | 422 idempotency_key_reused. Use a new key for a new operation. |
"Same request" means the same path and the same body bytes: send the stored body again rather than serialising it anew.
Answers are kept for 24 hours per API key: another key of the same account (a colleague's, or the new key after a roll) never gets your stored answer, and the same request sent with it runs anew. What the endpoint itself answers is stored, 2xx and 4xx alike, except 429; 5xx and 429 answers never are, so a retry after a 500 or a 429 runs again. A request refused before the endpoint runs — key, scope, rate limit, terms or a malformed body — stores nothing, so once you fix the cause the same key works. PATCH takes no key: sending the same change twice has the same result.
external_id — idempotency that never expires
POST /v1/leads also recognises your own reference: a second create with an external_id you already used returns that lead (200) unchanged, even days later and without an Idempotency-Key. Use both: the key for safe retries, external_id so an import that loses its keys still cannot create a creator twice. Duplicate rules by Instagram handle: Leads.
A retry loop
- Generate the
Idempotency-Keyonce per operation and keep it. - On a timeout, a network error,
409 idempotency_in_progress,429or5xx: wait and retry with the same key and body. No429is stored,429 duplicate_limit_reachedincluded, so afterRetry-Afterthe same key runs the request again. - Wait
Retry-Afterseconds when the answer has that header, otherwise back off exponentially (1 s, 2 s, 4 s, … up to a minute). - Never retry other
4xxanswers unchanged: fix the request first.