Idempotent business commands
Add idempotency without breaking older callers
New callers can supply stable keys while older clients may retry without them. Define the transition behaviour explicitly instead of pretending every request is protected immediately.
In this article
Inventory caller behaviour
Identify web clients, mobile apps, jobs and integrations that submit the command. Determine how each retries and whether it can persist a key across connection loss or restart.
A server-generated key returned only after success does not help a caller whose first response was lost. The client or trusted upstream workflow needs an identity it can retain before dispatch, unless another business identifier provides the intended contract.
Record which callers cannot be updated promptly and the limitations of their existing behaviour.
Introduce the request record and contract
Deploy storage for scoped keys, payload binding and results. Add explicit handling for matching, conflicting and pending requests.
Decide what requests without keys do during transition. They may retain legacy semantics, receive a migration warning or be rejected for the protected operation after a deadline. Do not silently derive identity from payload alone unless that is a valid business rule.
Keep the response contract compatible enough for callers to understand pending and conflict states. A new status that old clients treat as an invitation to create a fresh request can undermine the migration.
Upgrade callers with failure tests
Make clients create a key once per intended action and reuse it on retries. Preserve it through the recovery states the client supports, including offline queues where applicable.
Test lost responses after commit and concurrent submissions from the upgraded client. Verify a user starting a genuinely new but identical action receives a new key.
Observe missing-key traffic by caller version and operation. This provides evidence for when enforcement can tighten without unexpectedly breaking supported integrations.
Enforce and retain compatibility deliberately
Once required callers are migrated, enforce the key requirement for the agreed operations. Keep the account and operation namespace stable across server releases.
Plan rollback so existing key records and results remain meaningful. Reverting to code that ignores them can duplicate requests already accepted under the new contract.
Document the retention and replay window for callers and operators. The migration is complete when the protected command has a consistent identity from the client through the effect, and remaining legacy paths are either removed or explicitly understood as having different guarantees.
Primary sources
AWS Builders' Library: idempotent APIsStripe: idempotent requestsReferences checked 11 September 2026.