Developers
Idempotency keys
Retry POST and DELETE requests safely with the Idempotency-Key header: replays, conflicts and how long keys last.
On this page
Networks fail. When a POST times out you cannot tell whether it worked. An idempotency key lets you send it again without doing the work twice.
How to use it#
- Make a new random value for each operation, for example a UUID.
- Send it in the
Idempotency-Keyheader. - If you need to retry, send the same request with the same key.
# Make one key per operation, then send the SAME key on every retry of that operation.
KEY=$(uuidgen)
curl https://studio-api.mutexai.net/v1/webhook-endpoints \
-H "Authorization: Bearer $MUTEXAI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d '{"url": "https://example.com/webhooks/studio", "events": ["*"]}'
# Network error or timeout? Send exactly the same request again with the same $KEY.
Where it applies#
| Requests | Idempotency-Key |
|---|---|
POST /v1/webhook-endpoints, DELETE /v1/webhook-endpoints/{id} | Optional, recommended |
| POSTs that spend credits (sets, backgrounds, logos), coming soon | Required. Without it you get 400 idempotency_key_required |
| GET requests | Ignored. GETs are always safe to repeat |
What happens on a retry#
| You send | You get |
|---|---|
| Same key, same request, first one finished | The stored response from the first request, with Idempotent-Replayed: true. Nothing runs again. |
| Same key, same request, first one still running | 409 request_in_progress with Retry-After: 1. Wait and retry. |
| Same key, different body or path | 422 idempotency_key_reused. Use a new key for a new request. |
| A key over 255 characters, or not printable ASCII | 400 idempotency_key_invalid. |
| First request ended in a 5xx error | Nothing was stored, so the retry runs normally. |
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true
X-Request-Id: 01JD3YG6T8V0X2Z4B6D8F0H2K4
Details#
- "Same request" means the same method, path and JSON body. The order of JSON keys does not matter.
- Keys belong to one API key. Two API keys can use the same value without clashing.
- Keys are kept for 24 hours. After that, the same value counts as new.
- Error responses (4xx) are stored and replayed too, so a retry of a bad request gets the same error.
- For credit spending, the same key also protects the ledger: even in the worst case, one key can only be charged once.
Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.