Idempotency Expiration

Overview

Idempotency expiration is the point at which a service no longer guarantees that it retains the key and stored result needed to recognize a repeated request. Expiration ends the technical idempotency guarantee, not necessarily the business obligation. A short window can permit late retries or replays to recreate payments.

Services typically keep idempotency records for a documented retention window and may remove them afterward. These records support Duplicate Request and let an operator reproduce the result from authoritative evidence rather than relying on a dashboard snapshot or a provider’s latest status alone.

A request repeated after that window can be treated as new unless a separate business-level uniqueness rule still prevents duplication. Unlimited retention creates storage and privacy burdens and can block future legitimate operations if key namespaces are not designed correctly.

The expiration policy should reflect retry duration, delayed message delivery, financial reversibility, storage constraints, and audit requirements. Important failure modes include duplicate or out-of-order delivery, incompatible schemas, lost acknowledgements, unbounded retries, stale consumers, forged messages, and replay that creates a second financial action.

Clients need to know the window and should not assume that a very old key remains protected indefinitely. The final control should feed API Security , preserve the original evidence, and document any correction, override, or manual action. The contract should define identifiers, schema and version, authentication, ordering, idempotency, retry behavior, error handling, and the service responsible for authoritative state. Controls should preserve original payloads, correlation and causation identifiers, delivery attempts, validation results, consumer acknowledgements, and any replay or dead-letter action.