Idempotency
Idempotency
Keep one operation key through every retry of the same public write.
How it works
Every POST, PATCH and DELETE /v1/… resource write requires Idempotency-Key: 1–128 printable, non-space ASCII characters. A UUID works. Records are retained for 24 hours. The key belongs to the key or OAuth connection, and the canonical request includes method, path and body.
Missing or malformed keys return 400 idempotency_key_required. GET requests do not need one. OAuth protocol POSTs use their own protocol guards, not this header. MCP writes use the idempotency_key tool argument.
Retry safely
Create the key before the first attempt and persist it with your queued operation. Reuse the identical request and key after a lost response. A completed replay returns the stored status/body, including the same approval proposal. A request already pending returns 409 request_in_progress.
An ambiguous server failure leaves the operation pending to prevent duplicate side effects. Reconcile its proposal/status or contact support with the request id; do not generate a new key to force it through.
Conflicts
Reusing a key for another path, method or body returns 409 idempotency_conflict. Changed input is a separate reviewed operation. Expiration of an idempotency record is not authorization to repeat an operation whose outcome is unknown.