Networks fail in ambiguous ways. A client may time out after the server commits an operation and retry because it cannot tell whether the first request succeeded. Idempotency makes these retries safe.
Identify operations that need protection
Payments, order creation, provisioning, and external notifications often need idempotency. A read request is naturally repeatable, but a command that creates a resource may not be.
Use stable idempotency keys
Accept a client-generated key scoped to the authenticated actor and operation. Store the key, request fingerprint, processing state, and final result. Reusing a key with a different request body should produce a clear conflict rather than silently returning an unrelated result.
Coordinate concurrent requests
A unique database constraint should prevent two requests from claiming the same key simultaneously. Use a transaction to create the idempotency record and persist the business outcome consistently.
Define retention
Keep keys long enough to cover realistic retry windows and operational recovery. Avoid retaining unnecessary sensitive request payloads.
Checklist
- Identify commands with duplicate-side-effect risk.
- Scope keys to actor and operation.
- Enforce uniqueness in the database.
- Reject key reuse with different input.
- Define retention and replay behavior.