Skip to main content
Use an idempotency key when the endpoint supports it, and reuse that key only for a retry of the same logical request with the same payload. A new action needs a new key.

​
Visibility writes

Supported visibility mutations accept an optional Idempotency-Key header of up to 255 characters. Repeating a stored successful request with the same key and body returns its recorded response. A different body with the same key returns a conflict. A replayed response includes Idempotent-Replay: true. Support is endpoint-specific. In particular, the prompt rerun endpoint does not implement this replay header. Do not automatically resubmit a rerun after an ambiguous network outcome; inspect the prompt’s answer state first.

​
Data commands

Data commands that require Idempotency-Key validate a 16–160 character value containing letters, digits, colons, underscores, or hyphens. Preserve that key through a retry. A command can report a retryable conflict while the original command is still in progress. Keep the resource and version identifiers returned by each command. When an endpoint requires expectedRevision, send the revision you last read. Idempotency identifies a logical command; a revision check protects against applying it to a resource that has changed.

​
Build a bounded retry policy

  1. Separate reads from mutations in your client.
  2. Persist a mutation’s key before sending the request.
  3. Retry only the same operation and payload after a retryable outcome.
  4. Honour Retry-After and use bounded backoff.
  5. Stop on a non-retryable validation, permission, or conflict error.
Idempotency is not permission to issue competing writes concurrently. Serialise changes to the same resource where their order matters. See errors and rate limits and Data operations.