Idempotency
Send an Idempotency-Key on POST requests so a retry after a timeout never creates the same thing twice.
Networks fail after the request was processed. To make retries safe, send an Idempotency-Key header on any POST:
curl -X POST https://api.kuikcode.com/v1/codes \
-H "Authorization: Bearer kc_live_..." \
-H "Idempotency-Key: order-8812-code" \
-H "Content-Type: application/json" \
-d '{ "name": "Order 8812", "destination": { "type": "url", "url": "https://example.com/o/8812" } }'- The key is any string up to 255 characters that is unique per operation on your side: an order id, a UUID, a database row id.
- A successful response is stored for 24 hours per API key. Repeating the request with the same key within that time returns the stored response with the header
Idempotent-Replayed: trueand creates nothing new. - Only successful responses are stored. A failed request can be retried with the same key.
- Keys are scoped to the API key that sent them.
What a retry can get back
| Situation | Response |
|---|---|
| Same key, same request, first one finished | The stored response, with Idempotent-Replayed: true |
| Same key, same request, first one still running | 409 idempotency_in_progress, retry in a moment |
| Same key, different endpoint or payload | 422 idempotency_mismatch, use a new key |
| Same key, first one failed | The request runs again |
Keys are recorded in the database with a uniqueness rule, so two simultaneous requests can never both create a row: the first reserves the key, the second is told it is in progress. A request that fails frees its key at once. If the operation succeeded but its result could not be recorded, the key stays reserved and later retries get a 409 explaining that the outcome is unknown; list the resource to confirm, then continue with a new key. Duplicating a write is never the outcome.
PATCH and DELETE are naturally repeatable and ignore the header.