Idempotent operation
- Standard term
An idempotent operation is an action whose end result is the same whether it runs once or several times.
Agents retry because connections drop and services time out, often without knowing whether the first try went through. A step that sets something, such as marking a task done, lands in the same place every time. A step that adds, sends, or charges repeats its effect, unless it first checks whether it already happened.
Where you’ll meet it
You set up an agent that adds new sign-ups from your website's form to your newsletter list. One night the connection dropped partway through, and the agent ran again. Three people now get every newsletter twice, and one has written to complain.
What to do
Remove the three duplicates, then ask the agent to change the step from “add this person” to “add this email address if it isn't on the list yet.” To test it, run last night's batch of sign-ups again and check that the list doesn't grow.
Easy to mix up
| Idempotent operation | Idempotency key |
|---|---|
| How the step itself is written | An ID sent along, which the receiving service remembers |
Check yourself
Your agent's cleanup step times out, and you can't tell whether it ran. Which step is safe to run again without checking first?
Go deeperMathematics named it, and the web's standards say which requests have it
In mathematics, an operation is idempotent when doing it twice gives the same result as doing it once, as with rounding to the nearest whole number. The HTTP standard that web services follow marks GET, which fetches something, PUT, which replaces what is stored at an address, and DELETE, which removes it, as idempotent. POST, which usually creates something, is not, so a retried POST can make a duplicate.
When an action has to add or charge, the receiving service can catch retries by their idempotency key, and payment services such as Stripe accept one with each request. It protects only retries that reuse it, and only while the service keeps it, so a retry with a fresh key, or one arriving after the key expires, charges again.
The end result here means the stored data. Effects outside it can still happen twice, such as a second notification or a second logged visit, so each one that must happen only once needs its own check.