Record the key and payload identity together
Stripe documents parameter comparison and key retention for API v1, alongside different version-specific behaviour. Record the actual target API family/version and its idempotency rules with the command evidence. These guarantees do not automatically apply to another API. The sample record below is a local contract.
| Command | Key | Payload | Decision |
|---|---|---|---|
| Original reservation | CMD-41 | item=A, quantity=2 | Store before send |
| Uncertain retry | CMD-41 | item=A, quantity=2 | Same intent, same key |
| Approved quantity change | New command after reconciliation | item=A, quantity=3 | Do not reuse CMD-41 with changed parameters |
Handle retention expiry deliberately
Keep a payload fingerprint and a controlled command/result reference. If a retry arrives after the target’s key retention, reconcile the original operation before submitting again. Generating a fresh key to bypass a conflict can create a second operation.
An old key returns a parameter mismatch. Should the client regenerate a key automatically?
Show the worked answer
No. Identify whether the intended request changed or the retry was corrupted. Reconcile the original result, then authorise a separate command if a real change is required.