Idempotency
Retry a create safely, without making it twice.
A request can fail in a way that leaves you unsure whether it worked, such as a timeout, a dropped connection or a 5xx. For requests that only read, you just retry. For requests that create something, retrying could create it twice. An Idempotency-Key makes the retry safe.
How it works
Send an Idempotency-Key header with a create request:
Idempotency-Key: 9b2f6c1e-5d1a-4c8e-9f0a-3e7b2d4c6a18- Same key, same body, within 24 hours: you get the response of the first request again (same status, same resource). Nothing new is created.
- Same key, different body:
409 idempotency_conflict. A key stands for one request. - Same key while the first request is still running:
409 conflict. Wait a moment and retry. - A request that failed (any error) doesn't keep its key: retrying with it runs the request again.
Keys are 8–128 characters of A-Z, a-z, 0-9, _ and -. They're scoped to your account, so another account's keys never collide with yours.
Choosing keys
- Use a new key for every new thing you create: a UUID is ideal.
- Reuse a key only to retry the same request.
- Derive it from your own record when you have one (for example
webinar-for-event-4812), so even a restarted worker retries with the same key.
Retrying
Retry on timeouts, connection errors, 429 (after Retry-After) and 5xx, with exponential backoff and jitter. Keep the key and the body the same on each attempt. Never retry a 4xx other than 429 unchanged: it fails the same way.
Which requests take one
Create a webinar. Each new create endpoint will take one too, and its reference says so.