Idempotent business commands
Choose retention around the actual retry window
Idempotency records consume storage, but deleting them too soon weakens replay protection. Base retention on client behaviour and downstream guarantees.
In this article
Find the longest legitimate replay path
List automatic retries, offline clients, queued jobs and operator recovery. A web request may retry within seconds, while a mobile device can reconnect much later. The retention requirement should reflect the paths the product supports.
Distinguish a retry of the same intention from a new action. Keeping keys forever is not a substitute for defining that meaning, and expiring them quickly does not make old replay safe.
Document what the service does when a key arrives after its record has been removed. Callers need that boundary before relying on delayed recovery.
Estimate record volume and size
Calculate request volume over the retention window and include indexes, payload fingerprints and stored results. Large response bodies can dominate storage even when the key itself is small.
Consider retaining a compact operation reference rather than unnecessary internal data, provided the documented result can still be reconstructed reliably and authorised access is preserved.
Separate active or uncertain requests from completed records eligible for cleanup. An old unresolved operation may need investigation rather than automatic deletion based solely on age.
Align local and downstream windows
If an external service provides idempotency with its own retention policy, the application's replay guarantee cannot exceed that protection without another reconciliation mechanism.
For example, retaining a local pending record for a long period does not make it safe to resend to a provider that has already forgotten the original key. The application must establish the original outcome or use a deliberate recovery procedure.
Verify current provider semantics rather than assuming all services cache the same results or retain keys for the same period.
Test cleanup as part of correctness
Exercise requests just before and after the configured expiry boundary. Confirm cleanup does not race with an active retry or remove records still needed by an in-flight operation.
Monitor cleanup volume, old uncertain records and storage growth. Use these observations to adjust the design without silently changing the contract callers depend on.
The economical choice retains enough evidence for the actual recovery window while avoiding unnecessary payload copies. Retention is part of the idempotency guarantee, so changing it deserves the same care as changing the execution code.
Primary sources
Stripe: idempotent requestsAWS Builders' Library: idempotent APIsReferences checked 11 September 2026.