Skip to main content
Send an Idempotency-Key header with a POST request. If the request times out or the connection drops, send it again with the same key. It runs once and is charged once.

Rules

What you get back

When a key is freed

A key is freed when the request did nothing, so you can send it again.

Ambiguous timeouts

A 504 service.timeout carries "ambiguous": true. The request may have completed and charged.
1

Send the same request with the same key

If the first request finished, you get its answer with Idempotent-Replayed: true. If it is still marked as running, you get 409 idempotency.in_progress.
2

On 409, wait and repeat

Wait for Retry-After and send again.
3

Check before you give up

GET /v1/credits lists the latest charges. Check it before you send the request with a new key.
A key whose request never recorded an answer stays in progress for 6 minutes, then frees. A retry with the same key after that runs the request again and could charge again. If you saw a 504, check GET /v1/credits first.

Recommendations

  • Generate one key per logical request, and reuse it only for retries of that request.
  • Do not reuse a key for a changed body. Changing max_credits or one identifier makes it a different request.
  • Send the body with the same content on every retry.
The MCP server and the CLI attach a key to every paid call and retry for you. The SDK does not send one. Related: Errors, Rate limits, Credits.