Idempotency

Every mutating POST, PUT, PATCH, or DELETE requires Idempotency-Key, except operations explicitly marked as read-only despite their verb (currently signing preview and waiver resolution). The key must be 1–64 characters from A-Za-z0-9._-.

Reservations are unique across the workspace for (group, partner-v1, key), so credential rotation cannot execute the same logical request twice. The request hash covers method, exact URL/query, and a stable serialization of the parsed body.

State	Result
First claim	Handler owns the reservation
Completed, same request	Stored status/body replayed with Idempotent-Replayed: true
Same key, different request	409 idempotency_key_reused
Matching unfinished claim under five minutes	409 idempotency_key_in_progress
Matching unfinished claim at least five minutes old, or uncertain persistence	409 idempotency_outcome_unknown

This is fail-closed duplicate mitigation, not exactly-once delivery. A reservation is created before validation/handling and is never automatically released or taken over. Only completed outcomes are eligible for cleanup after their 24-hour replay window. Completion uses an acknowledged compare-and-set; uncertainty does not return the handler body.

For idempotency_outcome_unknown, assume the business write may have committed. Stop. Do not switch key, credential, URL or payload to bypass the reservation. Reconcile state and contact support with the server request_id—never with the secret or Authorization material.