Overview
Clients retry requests when a connection times out or a response is lost. The server may have completed the first request even though the client never received its response. Idempotency keys let the server recognize a retry and return the original outcome instead of repeating the action.
Require a client key
For operations that create expensive or irreversible effects, require a high-entropy idempotency key. Scope it to the authenticated account and operation. Apply length and character limits, and reject empty or malformed keys.
Persist the result atomically
Create a table with a unique constraint over account, operation and idempotency key. Store a request fingerprint and processing state. The unique constraint prevents two concurrent requests from both claiming the same key.
Detect key reuse with different input
Hash a canonical representation of the relevant request fields. If the same key arrives with a different fingerprint, return a conflict rather than silently reusing an unrelated result. Do not include secrets or volatile headers in the fingerprint.
Coordinate side effects
A database transaction can protect database changes, but it cannot automatically make an external payment, email or third-party API call transactional. Use an outbox or provider-side idempotency support where available. Define how in-progress requests and failed operations are recovered.
Retention policy
Keep idempotency records for at least the maximum retry window promised to clients. Document expiration behavior; after a key expires, the same request may be treated as new.
Checklist
- Scope keys to identity and operation.
- Enforce a unique database constraint.
- Store and compare request fingerprints.
- Handle concurrent requests atomically.
- Coordinate external side effects separately.
- Document key retention and retry semantics.