Skip to main content
Idempotency-Key is enforced end-to-end for both OAuth Bearer and yt_live_* / yt_test_* API-key auth. Send it on any write and a retried request with the same key returns the original response instead of executing twice.

​
The problem

Your POST to /api/v1/campaigns/{id}/leads:bulk timed out. Did we receive it? Retrying naively could double-insert. Retrying with an idempotency key lets us recognize the retry and return the original response.

​
How it works

Send a unique header on write endpoints:
We’ll dedupe on (tenant_id, key) for 24 hours. Retries with the same key within that window return the original response (same HTTP status, same body).

​
Generating keys

Use a UUID v4 per logical operation. The operation, not the attempt: if attempt 2 has a different key than attempt 1, we treat them as independent requests.
Python

​
Idempotency vs webhook event_id

Two separate ideas that solve opposite-direction problems: You use both — client-side keys for safe POST retries, event_id dedup for safe webhook replays.

​
Works on which endpoints

All POST / PUT / PATCH on /api/v1/*. GET / HEAD / DELETE don’t need it (already idempotent by HTTP semantics, modulo DELETE being “at most once” — we return 204 whether or not the resource previously existed). The header is optional everywhere it’s accepted — omit it and the endpoint runs normally with no dedup.