Your Idempotency Key Defines the Operation
Adding an idempotency key to an API doesn't automatically make the operation idempotent.
The key needs to identify the operation you want to execute once.
Consider payment creation:
POST /payments
Idempotency-Key: order-123-paymentThe client times out and retries:
POST /payments
Idempotency-Key: order-123-paymentThe server recognizes the same logical operation and returns the previous result instead of creating another payment.
Now imagine generating a new key for every retry:
Request 1 → 7f9a...
Request 2 → 82bc...
Request 3 → a14e...From the server's perspective, those are three different operations.
A good idempotency key should match the scope of the business operation.
Think about:
- What exactly should happen once?
- How long should the key remain valid?
- Which caller owns the key?
- Should the same key with different payloads be rejected?
- Where is the result of the original operation stored?
Idempotency isn't about making requests unique.
It is about recognizing when multiple requests represent the same operation.
If every retry gets a new identity, the server has no reason to know it's a retry.