Idempotency, explained with a cup of coffee.
You order a coffee. The barista doesn't hear the confirmation, so you order again. Do you want two coffees? Your integrations face this question thousands of times a day, and the answer is almost always no.
By Anvexis Stack Engineering8 min read
What idempotent means
An operation is idempotent if doing it twice has the same effect as doing it once. The HTTP standard puts it precisely: a request method is idempotent if the intended effect on the server of multiple identical requests is the same as for a single request, and of the methods it defines, PUT, DELETE, and the safe methods such as GET qualifySource [1]. POST, the method most APIs use to create things, does not.
Why does it matter? Because the standard also says idempotent requests can be repeated automatically when a connection fails before the client reads the response, while a client should not automatically retry a non-idempotent request unless it has some way to know that repeating it is safeSource [1]. Networks drop responses all the time. Without idempotency, every retry risks a duplicate order, payment, or invoice.
Where duplicates come from
Picture an online shop sending an order to an ERP. The request reaches the ERP, the order is created, and the response travels back. Somewhere on the way, the connection drops. The shop never sees the response, so it does the sensible thing and retries. The ERP receives the same order again and creates it again. Now the customer has two orders, the warehouse picks twice, and someone spends an afternoon untangling it.
Nothing in this story is a bug in the usual sense. Networks drop connections, timeouts happen, and retries are the right response. The problem is that the operation wasn't designed to be safely repeated. That's the barista making a second coffee because they didn't hear you say it was the same order.
Some operations are naturally idempotent
Setting a value is idempotent: setting an order's status to shipped twice leaves it shipped. Deleting a specific record is idempotent in effect: it's gone after the first call. Creating something new is not: each call makes another one. Adding to a quantity isn't either: each call adds again.
So the first design move is to prefer “set” over “add” where the business allows it. “Set stock for product 42 to 17” survives a retry; “add 3 to stock for product 42” does not. When an operation genuinely has to create or add, you need the receipt number.
The fix is a receipt number
The client generates a unique key for each logical operation, such as a random identifier for “create this order”, and sends it with the request. The server stores the key with the result when it first processes the request. If the same key arrives again, the server skips the work and returns the stored result. Same coffee, not a second one.
Stripe's API is a good public reference. It saves the status code and body of the first request made with a given key and returns that saved response for retries, suggests random V4 UUIDs as keys, allows keys up to 255 characters, and advises against using sensitive data such as email addresses as keysSource [2]. Crucially, it compares the parameters of a repeated request with the original and returns an error if they differSource [2]. A reused key with a different order isn't a retry; it's a bug, and it should fail loudly.
The receipt number pattern
@router.post("/orders")
def create_order(body: OrderIn, idempotency_key: str = Header()):
with db.transaction():
if (existing := find_by_key(idempotency_key)):
if existing.request_hash != hash_of(body):
raise HTTPException(422, "Key reused with a different request")
return existing.response # same coffee, not a second one
order = place_order(body)
save_key(idempotency_key, hash_of(body), response=order)
return orderGetting the details right
Do the key check and the write in one database transaction, or two simultaneous retries can both see “no key yet” and both create an order. A unique index on the key column is the backstop: the second insert fails instead of succeeding twice.
Store keys long enough to cover the client's retry window. Stripe, for example, may prune keys once they are at least 24 hours old, after which a reused key is treated as a new requestSource [2]. Decide your own window from how long your clients keep retrying, and document it. Finally, think about what to store for failures. Returning the saved error for a retry is predictable, but make sure clients can tell a permanent error, such as invalid data, from a temporary one worth retrying with the same key.
What should the key represent?
A key identifies one business intention, not one HTTP request. “Create order 1048 from the web shop” is one intention, however many times the request is sent. Generate the key when the intention is born, store it alongside the pending work on the client, and reuse it for every retry, including retries after the client restarts.
Where the source system already has a stable identifier, such as the shop's order number or a bank transaction reference, you can derive the key from it. That gives you deduplication for free, even across clients that never heard of idempotency keys, as long as the identifier is truly unique in its system.
Queues and background jobs repeat work too
Most job queues promise at-least-once processing: if a worker crashes halfway through a job, the job runs again. A job that sends an invoice email or posts a payment must therefore be safe to run twice. Record that the side effect happened, keyed by the job's own identifier, and check before acting.
Design multi-step jobs so each step is idempotent on its own, or so the job can tell which steps already completed. A job that creates an invoice, then emails it, then marks the order invoiced should skip the first two steps on a rerun if they're already done. Exactly-once delivery is rare; exactly-once effect is something you build.
There's a standard on the way
Many APIs already accept an Idempotency-Key header, and the IETF's HTTP API working group is standardizing it. The draft, titled The Idempotency-Key HTTP Header Field, describes using the header to make non-idempotent methods such as POST fault-tolerant; at the time of writing it is an active Internet-Draft on the standards track, version 08 from October 2026Source [3].
It's still a draft, so details can change, but following its naming now means your API looks familiar to anyone who has integrated with a modern payment or commerce platform. If you're designing a new integration API, use the header name and the store-and-replay behaviour described above.
Webhooks need the same care
Webhooks are usually delivered at least once, which means sometimes more than once. A shop platform may send the same order-created event twice if your endpoint was slow to answer. Store each event's identifier when you process it, and ignore events you've already handled.
It also helps to process webhooks asynchronously: accept the event quickly, put it on a queue, and do the real work in a background job. Fast responses mean fewer retries from the sender in the first place, and the queue gives you a natural place to deduplicate.
What it looks like with Odoo
When integrating with Odoo, store the external system's identifier on the record you create, such as the shop's order number on the sales order, with a uniqueness constraint. Before creating, look it up. The database constraint is the final safety net if two requests race each other.
Log every attempt with the key, the outcome, and any error. When something goes wrong, the log shows whether a duplicate was prevented or a request failed and needs attention. Our Odoo API integration work builds this in from the first connector, and the same principle protects offline-first mobile sync, where retries are constant.
Idempotency checklist
- Prefer “set” operations over “add” where the business allows
- Every create or add endpoint accepts an idempotency key
- Key check and write happen in one transaction, with a unique index
- Reusing a key with different parameters returns an error
- Keys are stored long enough to cover the retry window
- Retries reuse the same key, never a new one
- Webhook handlers deduplicate on the event ID
- External IDs stored on ERP records with a uniqueness constraint
Reconcile anyway
Even with idempotency keys and deduplication, integrations between systems drift over time. A message is lost, a record is edited by hand, or a bug slips through. Run a regular reconciliation that compares key totals and record counts between systems, such as orders, payments, and stock levels, and flags differences for review.
Reconciliation turns silent failures into visible tasks. It's the safety net under the safety net, and it catches issues long before customers or accountants do.
Test retries on purpose
Write tests that send the same request twice, that drop the response after the server commits, that send two identical requests at the same moment, and that deliver the same webhook several times. These scenarios happen in production every day, so they deserve tests as deliberate as the happy path.
Then test the unhappy variant: the same key with a different body. If that quietly succeeds, you have a duplicate-order bug waiting for the first client that reuses keys by mistake.
Frequently asked questions
Are GET, PUT, and DELETE requests always safe to retry?
Who generates the idempotency key, the client or the server?
How long should we keep idempotency keys?
Do we still need reconciliation if every endpoint is idempotent?
Sources
- [1]RFC 9110: HTTP Semantics, section 9.2.2 Idempotent Methods (opens in a new tab)IETF, June 2022
- [2]Idempotent requests (opens in a new tab)Stripe API reference
- [3]The Idempotency-Key HTTP Header Field (Internet-Draft) (opens in a new tab)IETF HTTPAPI working group, draft 08, 22 October 2026
Written by Anvexis Stack
We build Odoo, AI, web, and cloud systems for growing companies, and we write about the patterns we use. This is engineering guidance, not a product guarantee: check vendor details for your version before you decide. Last reviewed .
Keep exploring
Odoo integrations
Connect Odoo to Shopify, Stripe, banks, 3PLs, and legacy systems with signed webhooks, idempotent sync, retries, and reconciliation.
InsightsOffline-first sync
A design checklist for local writes, queued operations, conflict resolution, retries, and user feedback in offline-capable apps.
DevOpsCI/CD automation
CI/CD pipelines with automated tests, preview environments, GitOps deployments, and zero-downtime releases with fast rollback.
Next step
Got a tangled system? Let's untangle it together.
Thirty minutes with an engineer, no slide deck required. You'll leave with a clearer picture, whether or not we work together.
