Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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

  1. Generate the Idempotency-Key once per operation and keep it.
  2. On a timeout, a network error, 409 idempotency_in_progress, 429 or 5xx: wait and retry with the same key and body. No 429 is stored, 429 duplicate_limit_reached included, so after Retry-After the same key runs the request again.
  3. Wait Retry-After seconds when the answer has that header, otherwise back off exponentially (1 s, 2 s, 4 s, … up to a minute).
  4. Never retry other 4xx answers unchanged: fix the request first.