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. Prompt reruns support a 24-hour replay receipt: retry with the same key even if the original run has already completed. A deliberately new run needs a new key. Without a key, inspect the prompt’s answer state before resubmitting an ambiguous outcome. Prompt updates, single-prompt deletion, and bulk activation/deactivation also support 24-hour replay receipts. A retried update returns its original response even if the prompt was edited again in the meantime; it does not overwrite the later edit. A replayed deletion returns the same bodyless 204 success. Bulk status changes commit together, count duplicate identifiers once, and roll back together on failure. These endpoints do not yet offer an optimistic revision precondition; serialize intentional edits to the same prompt.

​
Tracked coverage writes

Tracked coverage creation and changes use a transactional receipt: the successful change and its retry response commit together. Reuse the same idempotency key within the 24-hour retention window. A record’s version is a separate concurrency check; after another change, read the current record before submitting a new command. Archiving retains the record, evidence and history. Restore the record before editing its metadata. A duplicate page remains a duplicate when archived; inspect and restore the existing record rather than repeatedly creating it. Tracked coverage changes do not run prompts or fetch the submitted URL.

​
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.