What is Idempotency in APIs
Idempotency is the property of an operation producing the same result whether executed once or many times. In HTTP: GET/PUT/DELETE are idempotent per RFC (a repeated request does not change state). POST is non-idempotent by default but can be made so via an Idempotency-Key header (Stripe pattern). Critical for payments, orders, any "create" endpoints where a network retry must not create duplicates.
Below: details, example, related terms, FAQ.
Details
- GET: idempotent (reads do not change state)
- PUT: idempotent (a repeated PUT yields the same final state)
- DELETE: idempotent (deleting an already-deleted resource = 404 or 204, state unchanged)
- POST: usually non-idempotent (creates a new entity each time)
- Idempotency-Key header: client sends a UUID; server caches response 24h; repeat request with same key returns the cached response
Example
POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{"amount":100,"currency":"USD"}Related Terms
Learn more
Frequently Asked Questions
Why does Idempotency-Key exist?
Network retry: server received the POST, processed it, but the response was lost in transit. The client thinks "it didn't go through, retrying" → duplicate. Idempotency-Key prevents that.
How long do I keep keys?
Stripe keeps them 24 hours. Enough for a retry window without bloating the DB.
Is GET idempotent even with rate limiting?
Yes. Rate limits do not affect idempotency. The request is either allowed and returns data, or rejected with 429 — in both cases state does not change.