Idempotency keys and safe retries

A phone loses signal after a request leaves but before the response returns. The client cannot infer whether the effect committed. Retrying is safe only when the operation’s contract handles repeated attempts; another option is querying the operation’s state. The distributed-systems path works through that uncertainty.

What the key has to promise#

The client generates the key, once, before the first attempt, and reuses it for every retry of that intention. That is the part teams get wrong: a key generated per HTTP call is not an idempotency key, it is a request id, and it protects nothing.

Scope the key to the authenticated owner and operation so one caller cannot replay another caller’s result. Store a canonical representation or digest of the parameters that define the intention, and reject reuse with different parameters. A byte-level body hash can reject harmless encoding changes; document how equivalence is decided. A 422 response is one possible policy, not a universal requirement.

The window matters too. Choose a retention policy. If a key is pruned and no other invariant prevents repetition, a retry after that window can perform the work again. Twenty-four hours is a common answer; whatever you choose, it belongs in the documentation, because it is part of the contract.

Where the record has to live#

In the same database, in the same transaction, as the effect it is protecting. Not in Redis beside the database, not in a middleware that writes after the handler returns — because every one of those introduces a moment where the effect exists and the key does not, and that moment is exactly the one the retry lands in. It is a transaction-boundary question before it is an idempotency question: state and the record of that state change commit together, or neither does. That ordering is why the architecture path reaches boundaries before it reaches this article.

# The claim and the effect commit together, or not at all.
# PostgreSQL READ COMMITTED; UNIQUE(key); no concurrent retention deletion.
# key is scoped to the authenticated owner and operation, not client text alone.
# request_hash is a canonical digest of the parameters that define this intent.
with conn.transaction():

    # RETURNING yields a row only if THIS statement did the insert.
    # One row: this request owns the work. No row: someone else does.
    claim = conn.execute(
        """INSERT INTO idempotency (key, request_hash, status)
           VALUES (%s, %s, 'in_flight')
           ON CONFLICT (key) DO NOTHING
           RETURNING key""",
        (key, request_hash),
    ).fetchone()

    # The branch is HERE, in the caller — not in the SQL. An empty RETURNING
    # is a signal this code has to act on; the database will happily run
    # whatever statement comes next, for the loser as readily as the winner.
    if claim is None:
        previous_hash, status, response = conn.execute(
            "SELECT request_hash, status, response FROM idempotency WHERE key = %s", (key,)
        ).fetchone()
        if previous_hash != request_hash:
            raise ValueError("same scoped key, different intention")
        return status, response  # caller translates the saved outcome to HTTP

    # Only the request that won the claim reaches these two statements.
    # (Not folded into the INSERT above with WITH: in Postgres a data-modifying
    # CTE and the main query share one snapshot, so an UPDATE in the same
    # statement would never see the row the INSERT just claimed.)
    conn.execute("INSERT INTO orders (customer, item_id) VALUES (%s, %s)", (4711, 88))
    conn.execute(
        "UPDATE idempotency SET status = 'succeeded', response = %s WHERE key = %s",
        ("{…}", key),
    )

Illustrative Psycopg-style code, not a complete HTTP handler or an executed PostgreSQL test. It assumes PostgreSQL Read Committed, a unique scoped key and no pruning during replay. A competing insert can wait for the first transaction: its uncommitted in-flight row is not a public progress record. After a committed conflict, the next SELECT has a new snapshot and reads the outcome. The loser must branch before doing work, and must check the stored request digest. Bound lock waiting and handle transaction failures. This model includes only effects inside this database transaction; the figure separately models sequential retries, not transaction locking.

The four ways it still breaks#

What to return on a replay#

Publish the replay contract. Stripe saves the first executed request’s status and body, including error results. EC2 can return updated creation state without repeating the action. Both prevent repeated effects within their stated scope; idempotence does not require byte-identical responses in every API.

A correctly scoped key and effect/replay contract can make retries safe within its documented window. It does not make the retry someone else’s problem, which is the usual reason a queue gets added — and most of the time the queue is the wrong answer.