On this page
What Is Idempotency (and Why Does It Matter for APIs)?
An idempotent operation can be retried safely — doing it once or many times has the same effect. Learn why payments and webhooks depend on it.
Quick answer
- An idempotent operation produces the same result whether it runs once or many times.
- Retries are only safe when the operation is idempotent — which is why payments and webhooks require it.
- The standard tool is an idempotency key: a client-supplied token that lets the server recognize and deduplicate a retry.
What is idempotency?
Idempotency is the property that repeating an operation has the same effect as doing it once. GET /users/42 is idempotent — reading twice changes nothing. A POST that charges a credit card is not idempotent by default: run it twice and the customer is charged twice. The distinction matters whenever a network can drop a response and the client retries.
Why it matters for APIs
Network failures are inevitable, and clients retry. If an operation isn’t idempotent, a retry can duplicate a payment, send two emails, or create two orders. For anything with a side effect — money, inventory, email — you must design for “the retry arrived twice” because in production, it will. This is exactly the failure that hits payment and webhook code, where a duplicate is a customer-visible bug.
How to make operations idempotent
The standard mechanism is an idempotency key: the client generates a unique key per logical operation and sends it with the request; the server records the key and the result, and returns the stored result if the same key arrives again. For example, Stripe’s API accepts an Idempotency-Key header so a retried charge isn’t a double charge. Natural uniqueness (a unique order ID) can serve the same purpose.
Where this bites vibecoders
AI-generated payment and webhook handlers routinely skip idempotency, because “handle the request” is the happy path and “handle the same request twice” is not. The result is double charges and duplicate records that only appear under retries. The habit: for any endpoint with a side effect, ask “what happens if this arrives twice?” and design the key before the handler.
Where AI coding assistants get this wrong
- Generating payment/webhook handlers with no idempotency handling.
- Ignoring that network retries will duplicate non-idempotent requests.
- Confusing idempotency with safety (GET is both; but idempotent ≠ read-only).
- Storing no record of processed keys, so retries can’t be deduplicated.
Checklist
- Identify every endpoint with a side effect.
- Add an idempotency key or natural uniqueness to each.
- Record processed keys and return the stored result on retry.
- Test the double-submit and retry paths explicitly.
- Make retries safe before making them automatic.
FAQ
What is the difference between safe and idempotent?
“Safe” means the operation doesn’t change anything (GET, HEAD) — a read-only guarantee. Idempotent means repeating it has the same effect, but it may still change state the first time (a PUT that sets a value is idempotent but not safe). All safe methods are idempotent; not all idempotent methods are safe.
Which HTTP methods are idempotent?
GET, HEAD, PUT, and DELETE are idempotent by convention. POST is not — which is why POST endpoints with side effects need explicit idempotency handling. The convention helps clients know what’s safe to retry.
How do webhooks use idempotency?
Webhook senders often include an event ID and retry on failure; receivers must use that ID to deduplicate events, so a redelivered webhook doesn’t process the same event twice. Idempotent webhook handlers are the standard contract between sender and receiver.