Idempotency
Idempotency describes an operation that can be repeated without causing additional unintended effects after the first successful application.
It is especially important when integrations retry requests after an uncertain failure.
What It Means in Practice
Imagine an integration sends:
Create a $100 payment.
The network connection fails before the integration receives the response.
Did the payment fail?
Or did the payment succeed and only the response get lost?
If the integration blindly sends the request again, the customer might be charged twice.
Idempotency provides a way to safely recognize the retry as the same intended operation.
HTTP and Idempotency
Some HTTP Methods are defined as idempotent by their normal semantics.
For example, repeated identical GET requests should not create repeated side effects.
POST requests commonly require additional protection when repeated actions could create duplicates.
MDN documents this distinction in its HTTP method reference. MDN HTTP method documentation
Idempotency Keys
Some APIs allow a client to send an idempotency key identifying a particular intended operation.
If the same request needs to be retried, the same key can be used.
Stripe explicitly supports idempotency keys so clients can safely retry requests without accidentally performing the same operation twice. Stripe's idempotent-request documentation
Where It Matters
Idempotency is especially useful for:
- Payments
- Orders
- Webhook processing
- Reservation creation
- Account creation
- Inventory adjustments
- Other operations where duplicates are harmful
Common Problems
Common problems include:
- Retrying failed POST requests blindly
- Generating a new idempotency key on every retry
- Webhooks creating duplicate records
- Duplicate orders after network errors
- Assuming timeout means the original action failed
- Applying idempotency only at the HTTP layer while downstream actions still duplicate
How to Improve
Identify operations where repeating an action would create a harmful duplicate.
Use provider-supported idempotency mechanisms where available.
For Webhooks, store and recognize unique event identifiers before performing non-repeatable actions.