The key and the fingerprint
An idempotency key is a client-chosen string that names one logical
operation, so a retry carries the same key as the original. retryfuse also
derives a request fingerprint: sha256(endpoint + canonical(body)),
computed over a canonical, key-order-independent serialization of the body. Two
requests that are semantically identical fingerprint the same; a changed field
fingerprints differently. You may pass a precomputed 64-character hex
requestHash, or pass the body and let retryfuse compute
it. An idempotency key is an optional string of at most
255 characters.
Exactly-once replay
When an operation has already completed under a key with a confirmed
committed effect, and the retry carries the same fingerprint, retryfuse returns
replay_stored: return the stored response
verbatim and do not run the handler a second time. The effect happens exactly
once no matter how many times the client retries.
The in-flight race
If a first request is still in_flight under the key when a duplicate
arrives, retryfuse returns brake. Two racing
retries never both execute: the second is braked while the first is in progress,
rather than running the effect concurrently.
Key reuse with a conflicting body
If the same key arrives with a different request fingerprint, that is
client misuse, not a legitimate retry. retryfuse returns
reject_conflict and refuses the request
rather than silently executing a different operation under a reused key.
How the decisions line up
| Idempotency state | Decision |
|---|---|
| No prior record, within failure and budget limits | replay_safe |
| Completed under this key, same fingerprint, effect confirmed | replay_stored |
| A request is still in flight under this key | brake |
| Completed under this key but the effect is unconfirmed | reconcile_required |
| Same key reused with a different request body | reject_conflict |
The uncertain-write case (reconcile_required,
evidence unknown) is where a key alone
is not enough: a completed record whose effect is unconfirmed must be reconciled
before any replay. The decision core is pure and versioned (contract version
1), so the same evidence always yields
the same verdict.
Next
See the contract reference for the exact JSON input, or why reconcile beats a blind retry for the uncertain-write case the key cannot settle on its own. The fixture matrix documents each state by example.