Scenario
Idempotency Keys
A charge endpoint that requires an Idempotency-Key header — replaying the same key returns the exact original response instead of creating a duplicate, the pattern real payment APIs use to survive network retries.
How this works
- · Every POST /charges call requires an Idempotency-Key header — omit it and the API returns 400 rather than silently processing the charge anyway.
- · The first request with a given key creates a charge and caches the response against that key. Replaying the exact same key returns the identical cached response — same charge id, an Idempotency-Replayed: true response header, 200 instead of 201 — instead of creating a duplicate.
- · A different key, even with the identical amount, is treated as a genuinely new charge — the key is the whole story here, not the request body.
What you'll practice
- Missing the Idempotency-Key header is a 400, not silently ignored
- The exact same key sent twice returns the SAME charge id both times (with an Idempotency-Replayed: true header) — a duplicate network retry never double-charges
- A different key with the same amount creates a genuinely new charge
- This is exactly how real payment APIs (Stripe and similar) protect against retry-caused duplicates
API reference
POST /api/scenarios/idempotent/charges
header Idempotency-Key: <any string>, body { amount } → { charge } (201 first time, 200 on replay)
GET /api/scenarios/idempotent/charges
→ every charge ever created — use it to confirm a replay did NOT add a second entry
curl -X POST https://playground.krishanchawla.com/api/scenarios/idempotent/charges -H "Content-Type: application/json" -H "Idempotency-Key: abc-123" -d '{"amount":49.99}'
curl -X POST https://playground.krishanchawla.com/api/scenarios/idempotent/charges -H "Content-Type: application/json" -H "Idempotency-Key: abc-123" -d '{"amount":49.99}' # same key, same response
- 1 Console