Idempotency
Idempotency means that requesting the same operation repeatedly has the same effect as applying it once. If the response to an order request is lost, the caller cannot easily tell whether no order was created or whether the order exists and only the response went missing. Identifying the request and returning its stored result lets the caller recover the result without creating another order.
An identical request body does not necessarily mean the same operation: a user may want to order the same product twice. The example below therefore combines an authenticated user identifier with a request key chosen by the caller. Reusing that key with different content is an error. AWS on idempotent API design
The diagram shows the sequence between create_order and db below. Both writes belong in one transaction so that an order cannot remain without its request record, or a request record without its order.
Creating one order and returning its result again
This standalone example uses Python 3.12 and SQLite from the standard library. owner identifies a user who has already passed authentication and authorization checks, and item is the entire request payload in this example. It uses one connection to an in-memory database, so the records disappear when the program ends.
import sqlite3
db = sqlite3.connect(":memory:", isolation_level=None)
db.executescript("""
CREATE TABLE orders(id INTEGER PRIMARY KEY, item TEXT NOT NULL);
CREATE TABLE requests(
owner TEXT NOT NULL, request_key TEXT NOT NULL,
item TEXT NOT NULL, order_id INTEGER NOT NULL,
PRIMARY KEY(owner, request_key)
);
""")
def create_order(owner, request_key, item):
db.execute("BEGIN IMMEDIATE")
try:
row = db.execute(
"SELECT item, order_id FROM requests WHERE owner=? AND request_key=?",
(owner, request_key),
).fetchone()
if row is not None:
if row[0] != item:
raise ValueError("KEY_REUSED_WITH_DIFFERENT_REQUEST")
order_id = row[1]
else:
order_id = db.execute(
"INSERT INTO orders(item) VALUES (?)", (item,)
).lastrowid
db.execute(
"INSERT INTO requests VALUES (?, ?, ?, ?)",
(owner, request_key, item, order_id),
)
db.commit()
return order_id
except Exception:
db.rollback()
raise
if __name__ == "__main__":
first = create_order("alice", "request-1", "book")
again = create_order("alice", "request-1", "book")
assert first == again
assert db.execute("SELECT COUNT(*) FROM orders").fetchone()[0] == 1
print(first, again) # 1 1
db.close()The first call stores the order and request record; the next call reads the order_id for the same key. Sending pen with that key raises ValueError and rolls back the transaction. The composite primary key treats another user's identical key as a separate operation.
The except block cleans up the transaction and propagates the original exception. The code does not retry automatically or substitute a default result. BEGIN IMMEDIATE and the composite primary key enforce write ordering and request identity in this SQLite example. A service with multiple connections must still check for duplicates and record the effect in the same database transaction.
Retrying after a lost response
Original diagram from Malcolm Featonby's Making retries safe with idempotent APIs, PDF page 4, printed page 3. The retry keeps the same identifier even when the first response never reaches the caller. The service recognizes the completed request and prepares a semantically equivalent response. Only the diagram was excerpted; its notation and arrows are unchanged. Original PDF, © Amazon Web Services.
Preventing duplicate effects and reusing responses are separate parts of the contract. A second call could return "already exists" while still applying the effect only once, but a caller trying to recover the first successful result needs to know which result it will receive. This example returns the stored order number.
Request key scope and retention
In production, decide which user and operation a key belongs to, how to determine whether request content is equivalent, how long records remain, and how to handle requests still in progress. Once a record is deleted, a late request can no longer be distinguished from a new one on that evidence alone. Design the valid retry window and retention policy together. The same key with a different payload must not be accepted as a successful duplicate. AWS on late requests and different intent
A database transaction does not also cover payments, email, or file writes outside that database. Use idempotency keys provided by the external service, or record an event for delivery with a Transactional outbox and design duplicate handling at the receiver. HTTP method idempotency likewise concerns the method's intended effect; response bodies and incidental logs may differ between calls. RFC 9110 §9.2.2