Idempotency
Definition
Property where performing the same operation multiple times produces the same result as doing it once, ensuring consistency in API operations.
Use Cases
- Stripe: Preventing duplicate credit card charges when clients retry a payment request due to timeouts or double-clicks — Stripe supports idempotency keys on API requests so a client can safely retry the same request. If the same idempotency key is reused with the same request parameters, Stripe returns the original result instead of creating a second charge. (Fewer accidental double charges, safer retries for unreliable networks, and simpler client-side error handling because retries don’t create duplicate payments.)
- PayPal: Avoiding duplicate order captures when a buyer refreshes the page or a merchant system retries after a network failure — PayPal APIs support idempotency via request identifiers (idempotency keys) so repeated submissions of the same operation can be recognized and handled as a single action. (Reduced duplicate transactions and fewer support cases related to double payments, improving customer trust and operational efficiency.)
Provider Equivalents
- AWS: Amazon API Gateway (Idempotency support for HTTP APIs)
Frequently Asked Questions
- What's the difference between idempotency and deduplication?
- Idempotency is a guarantee about an operation: calling it multiple times has the same effect as calling it once. Deduplication is a technique often used to achieve idempotency by detecting repeated requests (for example, using an idempotency key) and returning the original result instead of processing again.
- When should I use idempotency in APIs and workflows?
- Use idempotency whenever clients might retry requests or accidentally send duplicates—common with payments, order creation, booking/reservations, file uploads, and background jobs. It’s especially important for operations that create or charge something (POST-like actions) and for distributed systems where timeouts and retries are normal.
- How much does idempotency cost?
- Idempotency usually doesn’t have a direct licensing cost, but it can add operational costs: storing idempotency keys and results (database or cache), extra reads/writes per request, and occasional cleanup of old keys. Costs depend on request volume, retention window (how long you keep keys), and the storage/compute services you use.
Category: software
Difficulty: intermediate
Related Terms
See Also