A request can fail on the way back: the API did the work, but your software never received the answer. An idempotency key lets you send the same POST request again: while the API holds the first answer, it returns that answer and does not do the work again. Creating a site needs one, and every other POST request accepts one.
Send an idempotency key
Add an Idempotency-Key header with a value of your own, from 1 to 255 characters. A random UUID works well. Use a new value for each new piece of work, and the same value every time you retry it.
curl -X POST "https://api.kukie.io/v1/sites" \
-H "Authorization: Bearer $KUKIE_API_KEY" \
-H "Idempotency-Key: 5f0c1d1e-7a41-4b0e-9c57-2d1f3b6a8e90" \
-H "Content-Type: application/json" \
-d '{"domain":"shop.example.com"}'
What the API answers
| You send | The API answers |
|---|---|
| A key for the first time | It does the work. If the answer is a success, it stores the answer until 24 hours after the first request with that key. The stored answer is deleted within the hour after that. |
| The same key with the same request | The stored answer, with the header Idempotent-Replayed: true. The work is not done again. |
| The same key with a different request | 422 idempotency_key_reuse. Use a new key for a new request. |
| The same key while the first request is still running | 409 idempotency_in_flight with Retry-After: 5. Wait, then send it again. |
| No key, on an operation that needs one | 400 idempotency_key_missing. |
A request is the same when its method, its URL with the query string, and its body are the same.
What to know
- Only a success of up to 65,536 bytes is stored. After any other answer, such as an error, a retry runs the request again.
- Your organisation has a budget of 100,000,000 bytes of stored answers in each window of 25 hours. Each stored answer uses its own size and 512 bytes more. Past the budget a success is answered but not stored, so a retry runs the request again.
- If the first request never finished, a retry answers 409
idempotency_in_flightfor up to 120 seconds and then runs the request again. If the work may have been done in part, read the resource before you repeat it. - A replayed answer has the status and the body of the first answer, without its other headers, such as
Location,ETagandRetry-After. It shows the resource as it was then, not as it is now. - An idempotency key counts only for the API key that sent it. Another API key, or the new key after a roll, starts fresh.
- Before a replay is answered, it passes the limit checks that come before every request runs, so past one of those limits it answers 429 in place of the stored answer. It is counted only against the limits for every request, not against the limits of single operations, such as the number of sites you can create in an hour.
