Idempotency
Request deduplication and replay behavior.
Send an Idempotency-Key header when a route requires it. The key contains 1–255 printable
ASCII characters. HTTP header processing may trim spaces at the edges.
Route policy can require a key for every caller. Mutating requests from agent, customer,
and embedded-session principals also require one automatically. Safe methods are GET,
HEAD, and OPTIONS. Optional routes honor a key whenever supplied. Member sessions
cannot use tenant idempotency keys and receive forbidden if a key is supplied.
The currently available routes do not require a key; public mutation endpoints are not yet available.
A missing required key returns idempotency_key_required. Reusing a key with a different
request returns idempotency_key_reused. A matching request still in progress returns
409 conflict, potentially with operation correlation fields.
Keys are scoped to principal, company, test/live mode, method, and route template.
The request fingerprint also binds the concrete path, query parameters, body, and
Hms-Dry-Run header. JSON object key order is normalized; array order is preserved.
Non-JSON request bodies are matched by their exact bytes.
Completed responses and in-progress claims are retained for 24 hours from the original
claim. Authentication and authorization run before every replay. An ordinary replay keeps
the original status, body, and Content-Type, including the original body request_id;
request and rate-limit response headers are refreshed. Arbitrary response headers are
not replayed. An optional route-specific secret replay returns metadata with
already_issued: true without repeating the secret.
Validation and error responses are generally retained. A 5xx response after an audit transaction rollback releases the claim for retry. An uncertain commit leaves the claim in progress. Deduplication beyond the 24-hour retention period is not yet available.