Skip to main content
Every POST and PATCH requires Content-Type: application/json and a caller-owned Idempotency-Key. A key accepts 1–128 ASCII letters, digits and _.:/-. Request bodies are limited to 256 KiB.
Use a new key for a new logical change. For a retry, preserve the original key, method, path and JSON body. An identical retained request replays its original result with Idempotent-Replayed: true; a changed request conflicts with 409 idempotency_conflict. Authorization is checked again before replay.

​
Retention is bounded

Replay records live for up to 24 hours. Storage loss or eviction can shorten that protection. This is not a permanent exactly-once ledger. Save your own mapping from logical operations to returned resource IDs.

​
An uncertain write

A timeout, 5xx, request_in_progress or result_uncertain can mean the write committed but its final response was not saved.
  1. Read the target resource or use an exact identity lookup.
  2. Preserve the original request and key while reconciling.
  3. Do not generate a fresh key simply to force another attempt.
  4. If the state remains ambiguous, share the request ID with your account contact.
The CLI/MCP surface exposes mutation_may_have_succeeded and performs no automatic retries. A CLI dry-run validates locally and makes no HTTP call; it cannot establish current eligibility or reserve a resource.