Idempotency
Retry writes safely with Idempotency-Key.
Writes that start durable work or provider side effects require an idempotency key, so a retried request never publishes twice:
POST /v1/backfill-requestsPOST /v1/mediaPOST /v1/publish-requests
Send it as a header:
Idempotency-Key: 5b0e7d8e-6f6a-4c55-9d3e-2f1c9a0b7e41Use a fresh unique value (a UUID is fine) for each logical request, and reuse it only to retry that same request. Each endpoint that requires the header says so in the API endpoints reference.
Behavior
A key is scoped to your Organization and the operation. The same key may be used for a different operation, but not for a different payload on the same one.
| You send | Koil answers |
|---|---|
| The same key and payload, after the first request finished | The first request's result, again |
| The same key and payload while the first request is still running | 409 conflict with Retry-After |
| The same key with a different payload | 409 conflict |
An idempotency record resolves as soon as Koil has accepted the work and produced its ids (pub_…, med_…, bf_…); it does not wait for the work itself, such as a publish scheduled for next month. Records expire 24 hours after first use, after which the key may be reused with any payload. A request that dies mid-flight does not block its key for long: a record still in flight after 15 minutes is treated as abandoned, and the next request with that key takes it over.
Retrying failures
A request that failed should be retried with a new key: replaying the old one returns the same failure. For batch submissions (publish and backfill requests), the key covers the whole batch; to retry only the items that failed, submit just those items under a new key.
Reads, deletes, and updates are naturally repeatable and take no key.