When StreamHub's subscription checkout times out, the client retries the same POST. Without an idempotency key, the user gets charged twice. With one, the second request returns the original receipt — safe and expected.
Why retries happen
Sources of duplicate requests
- Client retries: Mobile apps retry on timeout; users double-tap submit buttons.
- Gateway retries: Load balancers replay requests when upstream returns 502/503.
- Message queue redelivery: At-least-once brokers redeliver unacknowledged messages.
- Webhook retries: Partners retry failed callback deliveries with exponential backoff.
HTTP GET, PUT, and DELETE are naturally idempotent. POST is not — you must design idempotency explicitly.
Idempotency key flow (checkout)
The rest of this guide is part of Pro
Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.
Still to come · 4 sections
- Idempotency key pattern
- Server-side flow
- Idempotency without a key store
- Distributed considerations
Test yourself
Answer these before moving on — recall is what makes it stick.