Idempotent API Requests, Done Properly
Designing requests so that repeating them has the same effect as sending them once, usually with an idempotency key.
Marcus Adeyemi
At a glance
- Idempotency keys let servers recognize repeated requests
- Safe methods GET and PUT are expected to be idempotent
- Retries clients and proxies retry automatically
- Storage keys must be stored with the original result
Why it matters
Why it matters: Networks fail mid-request, and clients retry, which can create duplicate orders or double charges.
Best practice
- Accept idempotency keys on create operations
- Store keys with their responses
- Return the original result for repeated keys
- Set a sensible key expiry
- Document retry behavior for clients
Common pitfalls
Watch out for:
- Non-idempotent payment endpoints
- Keys accepted but ignored
- Different results for the same key
- Retry logic with no server-side protection
When to call in a specialist
Bottom line Bring in help when APIs create payments or orders.
Where this comes from
- Stripe Documentation — Idempotent requests
- RFC Editor — RFC 9110 HTTP Semantics
The figures and practices above come from the sources listed.
Working on something like this?
We take on Web Design & Development work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.
Where to go next
Spotted something wrong? Report an error on this page. We correct on the page and say what changed.
