Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

Developers

Idempotency keys

Retry POST and DELETE requests safely with the Idempotency-Key header: replays, conflicts and how long keys last.

On this page
  1. How to use it
  2. Where it applies
  3. What happens on a retry
  4. Details

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#

  1. Make a new random value for each operation, for example a UUID.
  2. Send it in the Idempotency-Key header.
  3. If you need to retry, send the same request with the same key.
curl
# 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#

RequestsIdempotency-Key
POST /v1/webhook-endpoints, DELETE /v1/webhook-endpoints/{id}Optional, recommended
POSTs that spend credits (sets, backgrounds, logos), coming soonRequired. Without it you get 400 idempotency_key_required
GET requestsIgnored. GETs are always safe to repeat

What happens on a retry#

You sendYou get
Same key, same request, first one finishedThe stored response from the first request, with Idempotent-Replayed: true. Nothing runs again.
Same key, same request, first one still running409 request_in_progress with Retry-After: 1. Wait and retry.
Same key, different body or path422 idempotency_key_reused. Use a new key for a new request.
A key over 255 characters, or not printable ASCII400 idempotency_key_invalid.
First request ended in a 5xx errorNothing was stored, so the retry runs normally.
A replayed response
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.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.