Hermos API
Concepts

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.