Field Notes
Idempotency keys your clients will actually send
An API that documents idempotency but never validates key scope will surprise partners the first time they retry across resources.
API Design Advisory sessions often stall on a sentence like “clients should send an Idempotency-Key.” That sentence is incomplete. Keys need a scope: per resource, per operation, per account — and a retention window that matches how long partners retry.
We ask teams to walk a concrete failure:
- Client creates an order, times out, retries with the same key.
- Server created the order on the first attempt but failed to respond.
- What does the second attempt return, and which fields are guaranteed stable?
If the answer differs between the checkout service and the partner gateway, clients will invent their own reconciliation folklore. Write the guarantee into the contract kit before the first external caller ships.