Idempotency, errors, and retries

Idempotency keys

Every bearer mutation requires an idempotency key:

• REST: Idempotency-Key header;
• MCP: idempotencyKey tool argument.

Use a high-entropy key that is stable for one exact semantic operation. Records are scoped to credential and command and retained for seven days.

• Same key and identical request identity: returns the original complete result and audit.
• Same key with changed input, source, or caller: 409 IDEMPOTENCY_KEY_REUSED.
• An earlier request is still indeterminate: 409 IDEMPOTENCY_REQUEST_IN_PROGRESS.

Caution

Do not generate a new key merely because a mutation timed out. First retry the identical request with the same key. A new key may request a second real operation.

Error shape

Errors contain a stable code, message, retryability, correlation ID, and—when relevant—structured validation issues or retryAt.

Retry decisions

1. Preserve the correlation ID for support.
2. If retryable is false, correct the request or authority problem.
3. If retryAt exists, wait until that time.
4. For a transport timeout, retry the exact mutation with the same key.
5. For 409 version conflicts, read fresh state, review it, and create a new semantic request with a new key.

Authentication failures return HTTP 401 before MCP dispatch. Missing scope or live authority normally returns 403. Validation errors contain field paths; fix those rather than retrying unchanged.