Idempotency Keys

Best Practice: Idempotency Keys

Idempotency keys let clients safely retry write operations over an unreliable network without causing duplicate side effects. The client generates a unique key (commonly a UUID) and sends it with a request, for example in an Idempotency-Key header. The server records the key with the result of the first successful request; if the same key arrives again, the server returns the stored result instead of performing the operation a second time. Stripe popularized this pattern for payments, where a retried POST must never create a second charge. It matters because timeouts and connection drops are routine, and clients must retry, yet many operations are not naturally idempotent.

Step-by-Step Implementation Guidance

1. Require an idempotency key on all non-idempotent endpoints (POST creating resources, payments, transfers).
2. Have clients generate a unique key per logical operation and reuse it across retries of that same operation.
3. On the server, look up the key before processing; if found and complete, return the cached response.
4. Store the key, the request fingerprint, and the response, scoped to the account or API key.
5. Use an atomic insert or lock so concurrent retries with the same key do not both execute.
6. Reject reuse of a key with a different request body to catch client bugs.
7. Expire stored keys after a sensible window (Stripe uses 24 hours) to bound storage.

Common Mistakes Teams Make When Ignoring This Practice

• Retrying payments or creates with no key, producing duplicate charges or records.
• Generating a new key on each retry, defeating the purpose.
• Not handling concurrent requests with the same key, causing double execution.
• Storing keys without a request fingerprint, so a changed body silently returns the wrong result.
• Keeping keys forever, letting the store grow unbounded.

Tools and Techniques That Support This Practice

• Redis or a database table with a unique constraint for key storage.
• UUID libraries for client-side key generation.
• API gateways and SDKs (Stripe, Square) that support idempotency headers natively.
• Distributed locks for safe concurrent handling.

How This Practice Applies to Different Migration Types

• Cloud Migration: Cross-region retries are more common, making idempotency essential for correctness.
• Database Migration: Idempotent writes prevent duplicates when traffic is replayed during cutover.
• SaaS Migration: Integrating with billing or payment SaaS requires sending idempotency keys correctly.
• Codebase Migration: Adding keys while rewriting endpoints hardens them against the retries a migration introduces.

Checklist

• Non-idempotent endpoints require an idempotency key.
• Clients reuse one key across retries of the same operation.
• Server returns cached results for repeated keys.
• Concurrent same-key requests handled atomically.
• Request fingerprint validated against stored key.
• Keys scoped per account and expired after a window.
• Retry behavior documented for API consumers.