Understand
Idempotency and retries
Retry mutations safely without producing duplicate documents, revisions, publications, or webhook changes.
One key per logical action
Every mutating operation that declares key_required accepts an Idempotency-Key header. Use a UUID or another collision-resistant value and store it beside the logical action.
Idempotent mutation
Idempotency-Key: 0f776f46-a816-4b38-a88c-755713fe9141Replay and conflict behavior
A repeated request with the same body and key returns the original result. Reusing that key with a different body produces idempotency_conflict and must not be retried with the conflicting payload.
Safe retries
Retry transport failures, 429, and 503 with exponential backoff and full jitter. Reuse both the exact body and the exact idempotency key.