Idempotency key
- Industry term
An idempotency key is a unique label your app attaches to a request, such as a payment, so the receiving service recognizes a retry of the same request and avoids doing it twice.
The service records each key it sees and the result it sent back. When a request arrives with a key already on record, it returns that saved result and skips the action. Retries usually follow a timeout, when the sender can't tell whether its first try went through.
Where you’ll meet it
You had an agent build an automation that charges a client's card through your payment service whenever they book a lesson. One evening the payment service is slow to answer, the automation tries again, and a client emails you a screenshot of two identical charges.
What to do
Refund the duplicate from your payment service's dashboard. Then ask the agent to attach an idempotency key to every charge, made from the booking's ID, so each retry carries the same key and the service charges that booking once.
Easy to mix up
| Idempotency key | Idempotent operation |
|---|---|
| From a value the sender repeats and the service remembers | From the action itself, like setting a price to a fixed amount |
Check yourself
Your automation makes each charge's key from the client's email address. A client books two lessons at the same price, a few minutes apart. What happens to the second charge?
Go deeperA key works only within the service's rules for remembering it
Stripe, a payment service, accepts an Idempotency-Key header, a labeled line sent with a request, whenever a program asks it to create or change data. An IETF draft, a proposed internet standard, describes the same header for web requests in general. Services keep keys for a limited time, at least 24 hours at Stripe, and treat a key reused after that as new.
Services also differ on edge cases. A repeat that arrives while the first request is still running may get an error asking the sender to wait. A repeat with the same key and different contents, such as a new amount, is usually rejected, because the service can't tell which one was meant.
The key covers only the call to that one service. If the same automation also sends a confirmation email, that step needs its own guard, such as a record of the emails already sent.