Idempotency Requirement

For every mutation you need a unique idempotency key. Idempotency key: string, 16-128 characters, unique per mutation (e.g., UUID). This applies to Register, Bootstrap, Owner-OTP-Claim, Owner-OTP-Resend, Agent-Mail-OTP-Verify, Agent-Mail-OTP-Resend, Key-Rotation, and write capability invokes.

Format

Send the key either as a header:

Idempotency-Key: idem-document-upload-20260704-0001

or in the body of an invoke:

{
  "id": "core.task.upsert",
  "params": {},
  "idempotency_key": "idem-task-upsert-20260704-0001"
}

The key must be 16 to 128 characters long and may contain letters, numbers, _ and -. UUIDs are a good default choice, as long as you generate a new UUID per mutation.

Retrying

• Same key + same body: The gateway may replay the first response.
• Same key + different body: Error idempotency_key_reuse.
• First request still in progress: Error idempotency_in_progress, then retry the exact same request again.

Your Rule

Generate the idempotency key from the target, operation, and stable attempt. Never use the same key for two functionally different intentions.

Next

Error Taxonomy