Idempotency Key API Boundaries
An Idempotency Key is not merely a duplicate-request guard; it is a state-transition boundary design for POST APIs that involve uncertain external I/O.
· Practice memo · 32 min read · Hard
Prerequisites to keep in mind:
Key and Fingerprint
Key: the identifier the client assigns to one retryable unit of work, usually a high-entropy opaque string such as a UUID.
Fingerprint: a hash of the operation's content, e.g. the payment amount plus the product ID hashed together.
You have to look at both together; that combination is what catches a bug or an attack where different content arrives under the same Key.
Durable Replay
A request with the same Key has to return the same result even after the server dies and comes back, so the result is written to disk or a database. Idempotency survives a restart only because that store is durable rather than volatile.
Failure Release
A request must not get stuck in "processing" forever. If the server dies while handling it, that Key can stay in a "processing" state indefinitely, so TTL (Time-To-Live) expires the state after a set amount of time and explicit failure handling releases the Key on failure.
If the failure is certain not to have executed, leave it
failed_retryableorevictit so retries open up again.A failure that may have executed stays
unknownand goes to reconcile.
Introduction
An Idempotency Key is an API boundary pattern that lets a client safely retry the same request by allowing the server to determine "has this request already been processed?" HTTP itself defines idempotent methods as ones where sending the same request multiple times must produce the same intended effect on the server as sending it once. Under RFC 9110, PUT, DELETE, and safe methods are idempotent, but POST is typically used for resource creation or command execution, so without a separate mechanism it carries the risk of duplicate execution.1 The Idempotency-Key request header, which makes POST/PATCH safe to retry, has been discussed by the IETF HTTPAPI WG as a Standards Track Internet-Draft (draft-ietf-httpapi-idempotency-key-header). Because this draft is a document that expires and is renewed, you should verify its current status and each API provider's actual implementation syntax before use.2
The typical problem is ambiguous network failure, or more precisely uncertain external I/O. A client sends a request to create a payment, the server actually creates it, the connection drops before the response goes out, and from the client's side there is no way to know whether the operation succeeded. Resend the same POST /payments and the payment may be created twice; an idempotency key narrows that gray zone where the operation may or may not have succeeded.
Stripe's documentation explains that using an idempotency key allows you to repeat the same request even after a connection error, and that the server stores the result of the first request with a given key and returns that same result for subsequent requests with the same key. It also recommends using a value with sufficient entropy such as a UUID, and advises against including sensitive information like email addresses or personally identifiable information. It is also important to note that sending different parameters under the same key should be treated as misuse.3
What matters here is not "preventing duplicate requests" so much as identifying the same unit of work and reusing the same result for the same key and the same fingerprint. Matching keys alone should not be treated as the same request: a payment sent with amountCents=1000 and one sent with amountCents=9000 under the same key is not a retry but a client bug or a possible attack.
So even under the same key, a different payload is a different operation, which is exactly why the concept exists. Put briefly: identify the same operation semantically, then reuse its result.
Key formula to remember:
Idempotency Key = Identifier for the same logical unit of work being retried
Request Fingerprint = Semantic request hash used to prevent key misuse (canonical JSON + SHA-256)
Reserve -> Execute -> Complete | RetryableFail | Unknown
= Reserve execution ownership, then finalize the result into a replay/retry/reconcile-capable state
Fail(evict) = Release the reservation only for failures confirmed as not executed (prevents zombie keys)
Unknown/Reconcile = Do not evict failures that may have executed, such as gateway timeouts; send them to reconciliation
Replay = Return the stored response for the same key + same fingerprint
Boundary Policy = Separate domain-level duplication from infrastructure failure
1. The Problem
Say you're building a payment creation API.
POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"customerId": "cus-1",
"amountCents": 12000,
"currency": "KRW"
}The example above follows the Stripe-style opaque string convention, so no quotes.
A note on header syntax: if you strictly follow the IETF draft (-07),
Idempotency-Keyis an RFC 8941 Structured Header String, so the value must be quoted (e.g.,Idempotency-Key: "550e8400-e29b-41d4-a716-446655440000"). In contrast, Stripe and many other production APIs have historically used unquoted opaque strings. Implementations should therefore be explicit about whether they target IETF draft syntax or the de facto syntax of a specific provider.24
When a client hits a timeout and resends the same request, the server has to decide one of the following.
New key -> Execute payment creation
Completed with the same key + same fingerprint -> Replay the stored response
Same key still in progress -> 409 Conflict or 202 Accepted + Retry-After
Same key with a different fingerprint -> Idempotency key misuse (422)
Previous execution confirmed to have no side effect -> Allow retry
Previous execution result is unknown -> Disallow retry and reconcile
Everything here stays inside one domain: protecting a payment creation POST request with an idempotency key.
2. Key Expressions
The shared example keeps the idempotency store in memory. In production you swap it for a database, Redis, DynamoDB, a PostgreSQL unique constraint, transactions, and so on; the same state model is spelled out in four languages purely for syntax mapping, and it covers both concurrency (locking) and failure release (fail).
One caution: the in-memory example below is a minimal model for syntax mapping and only expresses InProgress/Completed. The production state model (failed_retryable, unknown, expired) is handled by the durable store in Section 7.
C#
using System;
using System.Collections.Generic;
public enum IdempotencyStatus { InProgress, Completed }
public enum IdempotencyDecisionKind { Execute, Replay, InProgress, KeyMisuse }
public sealed record ApiResponse(int StatusCode, string Body);
public sealed record IdempotencyDecision(
IdempotencyDecisionKind Kind,
ApiResponse? Response);
public sealed class IdempotencyEntry
{
public IdempotencyEntry(string fingerprint)
{
this.Fingerprint = fingerprint;
this.Status = IdempotencyStatus.InProgress;
}
public string Fingerprint { get; }
public IdempotencyStatus Status { get; private set; }
public ApiResponse? Response { get; private set; }
public void Complete(ApiResponse response)
{
this.Response = response;
this.Status = IdempotencyStatus.Completed;
}
}
public sealed class InMemoryIdempotencyStore
{
private readonly object gate = new();
private readonly Dictionary<string, IdempotencyEntry> entries = new();
public IdempotencyDecision Reserve(string key, string fingerprint)
{
lock (this.gate)
{
if (!this.entries.TryGetValue(key, out IdempotencyEntry? entry))
{
this.entries[key] = new IdempotencyEntry(fingerprint);
return new IdempotencyDecision(IdempotencyDecisionKind.Execute, null);
}
if (entry.Fingerprint != fingerprint)
{
return new IdempotencyDecision(IdempotencyDecisionKind.KeyMisuse, null);
}
if (entry.Status == IdempotencyStatus.InProgress)
{
return new IdempotencyDecision(IdempotencyDecisionKind.InProgress, null);
}
return new IdempotencyDecision(IdempotencyDecisionKind.Replay, entry.Response);
}
}
public void Complete(string key, ApiResponse response)
{
lock (this.gate)
{
this.entries[key].Complete(response);
}
}
// Remove the reservation only for failures where non-execution is certain, allowing retry with the same key.
// Failures where execution status is unclear are handled as unknown/reconcile in the operational model.
public void Fail(string key)
{
lock (this.gate)
{
if (this.entries.TryGetValue(key, out IdempotencyEntry? entry)
&& entry.Status == IdempotencyStatus.InProgress)
{
this.entries.Remove(key);
}
}
}
}TypeScript
type ApiResponse = Readonly<{ statusCode: number; body: unknown }>;
type IdempotencyStatus = "inProgress" | "completed";
type IdempotencyDecision =
| Readonly<{ kind: "execute" }>
| Readonly<{ kind: "replay"; response: ApiResponse }>
| Readonly<{ kind: "inProgress" }>
| Readonly<{ kind: "keyMisuse" }>;
type IdempotencyEntry = {
fingerprint: string;
status: IdempotencyStatus;
response?: ApiResponse;
};
export class InMemoryIdempotencyStore {
readonly #entries = new Map<string, IdempotencyEntry>();
public reserve(key: string, fingerprint: string): IdempotencyDecision {
const entry = this.#entries.get(key);
if (entry === undefined) {
this.#entries.set(key, { fingerprint, status: "inProgress" });
return { kind: "execute" };
}
if (entry.fingerprint !== fingerprint) {
return { kind: "keyMisuse" };
}
if (entry.status === "inProgress") {
return { kind: "inProgress" };
}
return { kind: "replay", response: entry.response! };
}
public complete(key: string, response: ApiResponse): void {
const entry = this.#entries.get(key);
if (entry === undefined) {
throw new RangeError("This is an unreserved idempotency key.");
}
entry.status = "completed";
entry.response = response;
}
public fail(key: string): void {
const entry = this.#entries.get(key);
if (entry !== undefined && entry.status === "inProgress") {
this.#entries.delete(key);
}
}
}(Note: inside Node's single-process event loop reserve is synchronous with no await, so the check-then-set is atomic. The moment you scale out to multiple instances this in-memory Map breaks, which is why you need the durable store from Section 7.)
Python5
import threading
from dataclasses import dataclass
from enum import Enum
@dataclass(frozen=True)
class ApiResponse:
status_code: int
body: object
class IdempotencyStatus(Enum):
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
class IdempotencyDecisionKind(Enum):
EXECUTE = "execute"
REPLAY = "replay"
IN_PROGRESS = "in_progress"
KEY_MISUSE = "key_misuse"
@dataclass
class IdempotencyEntry:
fingerprint: str
status: IdempotencyStatus
response: ApiResponse | None = None
@dataclass(frozen=True)
class IdempotencyDecision:
kind: IdempotencyDecisionKind
response: ApiResponse | None = None
class InMemoryIdempotencyStore:
def __init__(self) -> None:
self._entries: dict[str, IdempotencyEntry] = {}
# The GIL only guarantees single-bytecode atomicity. Compound operations like get -> if -> set are
# not atomic as check-then-act sequences, so protect the critical section with a Lock.
self._lock = threading.Lock()
def reserve(self, key: str, fingerprint: str) -> IdempotencyDecision:
with self._lock:
entry = self._entries.get(key)
if entry is None:
self._entries[key] = IdempotencyEntry(
fingerprint=fingerprint,
status=IdempotencyStatus.IN_PROGRESS,
)
return IdempotencyDecision(kind=IdempotencyDecisionKind.EXECUTE)
if entry.fingerprint != fingerprint:
return IdempotencyDecision(kind=IdempotencyDecisionKind.KEY_MISUSE)
if entry.status == IdempotencyStatus.IN_PROGRESS:
return IdempotencyDecision(kind=IdempotencyDecisionKind.IN_PROGRESS)
return IdempotencyDecision(
kind=IdempotencyDecisionKind.REPLAY,
response=entry.response,
)
def complete(self, key: str, response: ApiResponse) -> None:
with self._lock:
entry = self._entries[key]
entry.status = IdempotencyStatus.COMPLETED
entry.response = response
def fail(self, key: str) -> None:
with self._lock:
entry = self._entries.get(key)
if entry is not None and entry.status == IdempotencyStatus.IN_PROGRESS:
del self._entries[key]Rust
use std::collections::HashMap;
use std::sync::Mutex;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApiResponse {
pub status_code: u16,
pub body: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IdempotencyStatus { InProgress, Completed }
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IdempotencyDecision {
Execute,
Replay { response: ApiResponse },
InProgress,
KeyMisuse,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct IdempotencyEntry {
fingerprint: String,
status: IdempotencyStatus,
response: Option<ApiResponse>,
}
#[derive(Debug, Default)]
pub struct InMemoryIdempotencyStore {
entries: Mutex<HashMap<String, IdempotencyEntry>>,
}
impl InMemoryIdempotencyStore {
// The lock/unwrap handling is simplified here for learning purposes. In production code, avoid
// calling `panic` (via `expect`) on the request path; handle lock poisoning and missing responses as `Result` types instead.
pub fn reserve(&self, key: &str, fingerprint: &str) -> IdempotencyDecision {
let mut entries = self.entries.lock().expect("mutex poisoned");
match entries.get(key) {
None => {
entries.insert(
key.to_owned(),
IdempotencyEntry {
fingerprint: fingerprint.to_owned(),
status: IdempotencyStatus::InProgress,
response: None,
},
);
IdempotencyDecision::Execute
}
Some(entry) if entry.fingerprint != fingerprint => IdempotencyDecision::KeyMisuse,
Some(entry) if entry.status == IdempotencyStatus::InProgress => {
IdempotencyDecision::InProgress
}
Some(entry) => IdempotencyDecision::Replay {
response: entry.response.clone().expect("completed response"),
},
}
}
pub fn complete(&self, key: &str, response: ApiResponse) {
let mut entries = self.entries.lock().expect("mutex poisoned");
let entry = entries.get_mut(key).expect("reserved key");
entry.status = IdempotencyStatus::Completed;
entry.response = Some(response);
}
pub fn fail(&self, key: &str) {
let mut entries = self.entries.lock().expect("mutex poisoned");
// The check is completed first so that the immutable borrow from `get` and the mutable borrow from `remove` do not overlap.
let should_remove = entries
.get(key)
.is_some_and(|entry| entry.status == IdempotencyStatus::InProgress);
if should_remove {
entries.remove(key);
}
}
}3. Caller
The caller validates the HTTP request, builds the request fingerprint, and asks the idempotency store whether the key is already reserved. The actual payment creation I/O belongs to PaymentGateway, and the response policy belongs to the controller.
The fingerprint is generated not by a simple join but by serializing to canonical JSON (with sorted keys, etc.) and then applying SHA-256. A naive delimiter-based join can produce collisions where two distinct requests share the same fingerprint if a field value itself contains the delimiter (|). 6
import { createHash } from "node:crypto";
type CreatePaymentRequest = Readonly<{
idempotencyKey: string;
customerId: string;
amountCents: number;
currency: "KRW" | "USD";
}>;
type PaymentGateway = Readonly<{
createPaymentAsync: (request: CreatePaymentRequest) => Promise<Readonly<{ paymentId: string }>>;
}>;
// Minimal canonical serialization: sort only top-level keys. This is a minimal example for flat request DTOs only.
// Note: if key ordering within nested objects is unstable, a semantically identical retry may produce a fingerprint mismatch and be
// falsely flagged as 422 (key misuse). For nested objects, objects inside arrays, number
// normalization, Unicode escaping, and I-JSON constraints, either use a recursively sorting RFC 8785
// (JCS) implementation, or design your payload as a flat DTO to physically eliminate serialization complexity.
function canonicalJson(value: Record<string, unknown>): string {
const sorted = Object.keys(value)
.sort()
.reduce<Record<string, unknown>>((acc, k) => {
acc[k] = value[k];
return acc;
}, {});
return JSON.stringify(sorted);
}
function createPaymentFingerprint(request: CreatePaymentRequest): string {
const canonical = canonicalJson({
customerId: request.customerId,
amountCents: request.amountCents,
currency: request.currency,
});
return createHash("sha256").update(canonical, "utf8").digest("hex");
}
function validateCreatePaymentRequest(request: CreatePaymentRequest): void {
// Length is merely a heuristic for filtering out "obviously bad keys," not an entropy validation.
if (request.idempotencyKey.trim().length < 16) {
throw new RangeError("idempotencyKey is too short.");
}
if (request.customerId.trim().length === 0) {
throw new RangeError("customerId cannot be empty.");
}
if (!Number.isInteger(request.amountCents) || request.amountCents <= 0) {
throw new RangeError("amountCents must be an integer greater than or equal to 1.");
}
}
// NOTE: This function is an example policy hook; the default value is false (pessimistic policy).
// Network errors are all treated as 'Unknown (execution status indeterminate)' by default.
// In a real implementation, base the decision on the HTTP client/error type, the transmission stage, and the gateway contract,
// and return `true` only when it can be proven that "the request never reached the downstream" (e.g., a local exception raised before the external call).
// If a packet has already gone out, it must unconditionally be a reconciliation target.
function isDefinitelyNotExecuted(error: unknown): boolean {
void error;
return false;
}
export async function createPaymentApiAsync(
request: CreatePaymentRequest,
store: InMemoryIdempotencyStore,
gateway: PaymentGateway,
): Promise<ApiResponse> {
validateCreatePaymentRequest(request);
const fingerprint = createPaymentFingerprint(request);
let decision: IdempotencyDecision;
try {
decision = store.reserve(request.idempotencyKey, fingerprint);
} catch {
// On store failure, domains where duplication is costly (such as payments) should fail closed (reject the request).
return { statusCode: 503, body: { code: "idempotency_store_unavailable" } };
}
if (decision.kind === "replay") {
return decision.response;
}
if (decision.kind === "inProgress") {
return { statusCode: 409, body: { code: "idempotency_key_in_progress" } };
}
if (decision.kind === "keyMisuse") {
return { statusCode: 422, body: { code: "idempotency_key_reused_with_different_payload" } };
}
try {
const payment = await gateway.createPaymentAsync(request);
const response: ApiResponse = {
statusCode: 201,
body: { paymentId: payment.paymentId, status: "created" },
};
store.complete(request.idempotencyKey, response);
return response;
} catch (gatewayError) {
// The failure policy branches on whether execution has occurred.
// - Failures where it is certain that execution did not occur (e.g., failure before the gateway call) -> release via `store.fail` (allow re-execution). Prevents zombie keys.
// (allow re-execution). Prevents zombie keys.
// - Failures where execution may have occurred (gateway timeout, connection drop, etc.) -> do not evict. Leave the reservation
// as in-progress so it becomes a reconciliation target, or pass the same idempotency
// key to the downstream payment gateway to prevent duplicate charges.
if (isDefinitelyNotExecuted(gatewayError)) {
store.fail(request.idempotencyKey);
}
throw gatewayError; // Map to 5xx at the upper layer.
}
}Fail(evict) is only safe for failures where it is certain the operation was never executed. Failures where execution may have occurred should be treated as unknown/pending/reconcile targets, not evicted. The isDefinitelyNotExecuted above is a placeholder predicate that determines whether the gateway failed before the request was even sent (for example, failure before the connection was established, or a client-side error before transmission). In practice, a policy like Stripe's is common: once execution has started, even a failure response such as a 500 is stored and returned as-is to subsequent retries with the same key.3
Separation of concerns:
validateCreatePaymentRequest = validation of external input
createPaymentFingerprint = generation of a semantic fingerprint using canonical JSON + SHA-256
IdempotencyStore.reserve = key reservation / replay / misuse / in-progress determination
PaymentGateway = actual payment creation I/O
IdempotencyStore.complete/fail = storage of execution results / release of reservation on failure
createPaymentApiAsync = assembly of the API response policyThe idempotency store knows nothing about the payment domain; all it knows is the key, the fingerprint, and the response. Payment creation, DB persistence, and the external PG call stay with the layers above.
Crash window (caution):
store.failcuts down zombie keys, but an in-memory approach cannot fully close the window where the process dies right after the gateway succeeds and beforecompleteorfailruns. Closing it takes either (a) wrapping the domain write and the idempotency completion in one database transaction, as Section 7 describes, or (b) passing the idempotency key down to the payment gateway so that re-execution is deduplicated downstream.
4. Reading Order
Is an `Idempotency-Key` present?
-> Is the key sufficiently unpredictable? (for example, generated by the client as a UUID)
-> Can the payload fingerprint be computed deterministically? (canonical representation + hash)
-> Is this a new key?
-> Is this the same key with a different fingerprint?
-> Has this key already completed?
-> Is this key still in progress?
-> Was the previous execution confirmed to have no side effect? (if the result is unknown, do not retry)
-> Is the actual I/O executed only once?
-> Is the reservation released on eligible failure?
-> Is the result stored in a replayable form?
Idempotency code must not stop at "is this the same key?" — it must go all the way to "is this the same key AND does it represent the same intended request?"5. Boundaries and Misconceptions
An Idempotency Key is not authentication, so an attacker being able to mint an arbitrary key must never grant them permission. Always store a key together with a scope such as tenant, account, user, or API route, because judging on one global key lets different users' keys collide or leak information between them.
It also differs from deduplication, which is the general handling that merges the same data arriving several times. An Idempotency Key is an API contract in which the client states that "this request is the same unit of work as a previous attempt", and it is dangerous for the server to look at the payload alone and guess that two requests are probably the same.
Keep domain-side predictable rejections apart from infrastructure failures. A key that is already executing is a domain/API boundary collision, a different payload under the same key is client misuse, whereas a DB transaction failure, a Redis outage, or a payment gateway timeout are infrastructure failures. Turn them all into 500 or all into 409 and the retry policy breaks the moment you flatten the distinction.
Another common misconception is the idea that "idempotent means the response must always be identical." The HTTP definition of idempotency focuses on whether the intended effect on the server is the same. That said, in POST APIs based on an Idempotency Key, it is common practice to store the first response and return that same response on retries with the same key, purely for operational convenience. RFC 9110 also emphasizes that an idempotent request produces the same intended effect when repeated, while noting that the response itself may differ.1
Production failure modes:
Comparing only the key without comparing the payload fingerprint
Building the fingerprint with a simple join, leaving it vulnerable to delimiter injection and collisions
Including sensitive information such as email addresses, phone numbers, or social security numbers in the idempotency key
Storing the key as a global key without tenant/account scope
The reserve and domain write are not atomically coupled, resulting in duplicate execution
Failing to release the reservation on execution failure, leaving the zombie key perpetually in-progress
Conversely, unconditionally evicting failures with uncertain outcomes (such as gateway timeouts), which triggers duplicate charges
Not storing the status, body, and schema version required for response replay
No API contract specifying whether it is acceptable to return 200 instead of 201 on a retry with the same key
Ignoring idempotency store failures and proceeding directly to payment creation (a fail-closed violation)6. Incorrect Example
const processedKeys = new Set<string>();
async function createPaymentBadAsync(
request: CreatePaymentRequest,
gateway: PaymentGateway,
): Promise<ApiResponse> {
if (processedKeys.has(request.idempotencyKey)) {
return { statusCode: 200, body: { status: "already_processed" } };
}
const payment = await gateway.createPaymentAsync(request);
processedKeys.add(request.idempotencyKey);
return { statusCode: 201, body: { paymentId: payment.paymentId } };
}Why it's wrong:
Because the key is recorded after creating the payment, if the process dies immediately after a successful gateway call, a duplicate payment can occur on retry.
Without comparing the payload fingerprint, a different payment request sent with the same key will not be blocked.
Instead of replaying the stored original response, it fabricates a fake `already_processed` response.
There is no tenant/account scope.
Because the in-progress state cannot be represented, two concurrent requests can both reach the gateway.
Because storage is in process memory only, the implementation breaks in server restarts, scale-out, and multi-instance environments.This code looks like duplicate prevention, but it is not an idempotency boundary. A production API needs all of it: key pre-emption, fingerprint validation, atomic storage, a preserved replayable response, and failure release.
7. Production Scaling
In production you run a durable store instead of an in-memory one, meaning a store whose data is guaranteed to survive a process restart; put a unique constraint on scope + key and save the status, the fingerprint, and the response together.
CREATE TABLE api_idempotency_keys (
scope_id TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
request_fingerprint TEXT NOT NULL,
status TEXT NOT NULL CHECK (status IN
('in_progress','completed','failed_retryable','unknown','expired')),
response_status_code INTEGER NULL,
response_body JSONB NULL,
response_schema_version INTEGER NULL,
last_error_code TEXT NULL,
locked_until TIMESTAMPTZ NULL, -- Execution lease expiration for in-progress zombie reclamation
reconcile_after TIMESTAMPTZ NULL, -- Scheduled time for reconciling unknown-state records
created_at TIMESTAMPTZ NOT NULL,
completed_at TIMESTAMPTZ NULL,
expires_at TIMESTAMPTZ NOT NULL,
PRIMARY KEY (scope_id, idempotency_key)
);Transaction Abort Pitfall and the Correct Flow
You should not follow the pattern many developers commonly design: "INSERT, catch the unique violation error, then SELECT within the same transaction." In PostgreSQL and other strict RDBMSes, when a unique constraint violation occurs inside a transaction, the entire transaction is aborted, and any subsequent SELECT in that same transaction is rejected with "current transaction is aborted." For this reason, use an atomic upsert statement that does not throw an error, so that acquiring execution rights and querying are handled in one step.7
-- Attempt to acquire execution rights. `ON CONFLICT DO NOTHING` does not throw an error, so the transaction is not aborted.
INSERT INTO api_idempotency_keys
(scope_id, idempotency_key, request_fingerprint, status, locked_until, created_at, expires_at)
VALUES ($1, $2, $3, 'in_progress', now() + interval '5 minutes', now(), now() + interval '48 hours')
ON CONFLICT (scope_id, idempotency_key) DO NOTHING
RETURNING scope_id;
-- If `RETURNING` yields a row, this request has acquired execution rights.
-- 0 rows (conflict): already exists. Follow up with a separate `SELECT` to retrieve the status, fingerprint, and response.Recommended processing flow:
1. Start a transaction.
2. Run `INSERT ... ON CONFLICT DO NOTHING RETURNING`.
3. If `RETURNING` yields a row -> execution ownership acquired.
4. If it returns 0 rows -> run a separate `SELECT` to read the existing row. The transaction has not been aborted.
5. Fingerprint mismatch -> `422` misuse.
6. `status = in_progress AND locked_until > now()` -> `409 Conflict` or `202 Accepted + Retry-After`.
`status = in_progress AND locked_until <= now()` -> atomically transition to `unknown`, then reconcile.
7. `status = completed` -> replay the stored response.
8. `status = failed_retryable` -> allow retry. The previous attempt is confirmed to have had no side effect.
`status = unknown` -> disallow retry and reconcile. The side-effect status is unclear.
9. Only the request that acquired execution ownership may perform the domain write.
10. Commit the domain write and the idempotency row completion in the same transaction.
failed_retryable re-execution rights and locked_until reclamation
A failed_retryable row already exists, so INSERT ... ON CONFLICT DO NOTHING gets you no execution right; only the request that atomically flips the status back to in_progress wins the right to re-execute.
UPDATE api_idempotency_keys
SET status = 'in_progress',
locked_until = now() + interval '5 minutes',
last_error_code = NULL
WHERE scope_id = $1
AND idempotency_key = $2
AND request_fingerprint = $3
AND status = 'failed_retryable'
RETURNING scope_id;
-- RETURNING row exists -> this request acquires the right to re-execute
-- 0 rows -> another request already claimed it in the meantime, or the state has changedlocked_until is the signal for dealing with in-progress zombies. In payments, though, re-executing the moment a lock expires is dangerous, since the process may be dead while the external PG request actually succeeded, so the safe default is not to re-execute but to move the row to unknown.
`in_progress` and `locked_until > now()`
-> `409 Conflict` or `202 Accepted + Retry-After`
`in_progress` and `locked_until <= now()`
-> Do not retry. Transition to `unknown` and reconcile.So locked_until is not evidence that re-execution is safe; it is a signal that this request is not being processed normally and has to be reconciled. Flipping an expired in_progress row to unknown is an atomic UPDATE as well.
UPDATE api_idempotency_keys
SET status = 'unknown',
reconcile_after = now(),
last_error_code = 'in_progress_lock_expired'
WHERE scope_id = $1
AND idempotency_key = $2
AND request_fingerprint = $3
AND status = 'in_progress'
AND locked_until <= now()
RETURNING scope_id;That covers the request path, where a specific key + fingerprint is a given. A batch job or daemon sweeping expired in_progress rows may not know the fingerprint, so it runs on a reduced set of conditions.
UPDATE api_idempotency_keys
SET status = 'unknown',
reconcile_after = now(),
last_error_code = 'in_progress_lock_expired'
WHERE status = 'in_progress'
AND locked_until <= now()
RETURNING scope_id, idempotency_key;State transition summary:
- failed_retryable : Only requests that transition to `in_progress` via an atomic UPDATE hold execution rights.
- unknown : No client retry can acquire execution rights; only the reconciliation pipeline
transitions the record to `completed` or `failed_retryable`.
- expired in_progress : Do not auto-retry; transition to `unknown` and reconcile.In domains where duplicate execution is costly, such as payments, any gap between the domain write and the idempotency complete steps is dangerous, so bundle the internal domain write and the idempotency completion into the same DB transaction wherever possible. That said, the same transaction is not always the answer: never hold an external payment gateway (PG) call inside a long-running DB transaction, because a long transaction plus network I/O increases lock hold time and makes failure recovery harder. Back the external I/O with a PG-side idempotency key, an outbox, a payment_intent state machine, and a reconciliation job instead, and that is how you actually close the crash window described in Section 3.
Resolving the unknown state: the reconciliation pipeline
A request stuck in unknown, with no way to tell whether it executed, has to get its final status from a dedicated asynchronous pipeline. An unknown that nobody ever resolves is simply a hidden failure state, and resolution usually combines three approaches.
PG webhook ingestion is the authoritative source, since the success/failure webhook from the payment gateway is the most trustworthy final status. Find the row by the webhook's idempotency key or payment id and settle it as
completedorfailed_retryable.The periodic polling daemon is the backup: when a webhook is missing or late, it enqueues the
unknownrows whosereconcile_afterhas passedand checks their real status through the PG's query API (GET payment), then adjusts them.
The DLQ is the last net: anything polling cannot settle, or that blows past the retry limit, goes to a dead letter queue for an operator to look at and handle by hand.
Failure finalization also splits into categories. If it is confirmed that no payment object was created on the PG side, the row can transition to failed_retryable. Conversely, if a payment object was created but then declined or failed, it is safer to treat the unit of work as completed even though the domain outcome is a failure: store it as completed and replay the same failure response. Use failed_retryable only when you can prove that re-executing the same operation will not produce duplicate side effects.3
The principle to hold on to: while a request is unknown the client cannot re-execute with the same key, and nothing but this pipeline moves a state to completed or failed_retryable. That is what keeps an indeterminate result from spreading into a duplicate execution.
A TTL policy is also necessary. Stripe's documentation states that keys may be pruned no earlier than 24 hours after creation. In internal systems, domains with long retry windows, such as payments, orders, transfers, and reservations, may require a retention period longer than 24 hours. The retention period should be defined as the sum of the client retry window, the failure recovery window, and any audit requirements.3
expired is a policy call: physically delete the row, or keep it as a state.
A. hard delete: a pruning job physically deletes rows whose `expires_at` has passed.
B. soft expire: set `status='expired'` for auditing/analytics purposes and exclude the record from replay targets.Operational metrics:
api.idempotency.reserve.created.count
api.idempotency.reserve.replay.count
api.idempotency.reserve.in_progress.count
api.idempotency.reserve.key_misuse.count
api.idempotency.reserve.failed_retry.count
api.idempotency.reserve.unknown.count
api.idempotency.store.error.count
api.idempotency.zombie_key.count
api.idempotency.ttl_pruned.count
api.idempotency.reconcile.scheduled.count
api.idempotency.reconcile.resolved.count
api.idempotency.reconcile.failed.countkey_misuse in particular can be a security signal: a plain client bug, a replay attack that keeps changing the payload under the same key, or an SDK defect.
8. Comparison Notes: C# / TypeScript / Python / Rust
Language | Idiomatic Patterns | Caveats |
|---|---|---|
C# | record, enum, interface store, DB transaction |
|
TypeScript | discriminated union, | In a multi-instance Node environment, an in-memory |
Python | dataclass, Enum, repository class | The GIL does not guarantee check-then-act atomicity, so |
Rust | enum, | Never use |
- Language
C#
- Idiomatic Patterns
record, enum, interface store, DB transaction
- Caveats
lock + Dictionaryis a single-process example only, not a production store
- Language
TypeScript
- Idiomatic Patterns
discriminated union,
Map, controller boundary- Caveats
In a multi-instance Node environment, an in-memory
Mapbreaks immediately
- Language
Python
- Idiomatic Patterns
dataclass, Enum, repository class
- Caveats
The GIL does not guarantee check-then-act atomicity, so
threading.Lockis required
- Language
Rust
- Idiomatic Patterns
enum,
Mutex<HashMap>, explicit ownership- Caveats
Never use
expect/panic on the request path; keep the poison boundary and durable store boundary separate
C# expresses idempotency decisions clearly through record types and interfaces, TypeScript branches execute/replay/inProgress/keyMisuse cleanly with a discriminated union, and Python reaches the same shape with dataclasses and Enum, but do not mistake the GIL for a storage consistency model; explicit locking is still required. Rust's enum fits decision modeling well, but the Mutex<HashMap> and expect calls in these examples are for learning, and production needs a DB or a distributed store plus Result-based error handling.
Never transplant one language's idioms into another by force: there is no need to build an elaborate C#-style class hierarchy in TypeScript, and imitating TypeScript-style string unions in C# only weakens type safety. In Rust, rather than funneling everything into Result, defining a separate replayable decision enum is the accepted practice, since it keeps the intent clearer.
In the end, what counts as core programming practice depends partly on a language's limits and techniques, and partly on community convention.
9. Additional Considerations
Is this API idempotent through its HTTP method alone, or is it a
POSTcommand that needs an idempotency key?Is the fingerprint taken over the raw JSON string, or over canonical (RFC 8785 JCS) + hash?
When a different payload arrives under the same key, which fits the API contract best: 400, 409, or 422?
If the external PG call and the internal DB write cannot be one atomic operation, do you reach for outbox, saga, or a PG idempotency key?
Must a replay response be exactly the first response, or is a different status code fine as long as it carries the same resource id?
What should set the key TTL: the client retry window, the failure recovery window, or audit requirements?
When the idempotency store is down, do you block the request (fail-closed) or go ahead and accept the duplicate risk?
On execution failure, should you evict the reservation or mark it as failed? If there is any possibility the gateway succeeded, which choice is safer?
10. Summary
An Idempotency Key is an API boundary pattern that stops a retry from spreading into a duplicate execution when the network is uncertain.
Comparing keys alone is not enough; you also check that the same key carries the same request fingerprint (canonical + hash).
Reserve -> Execute -> Complete / RetryableFail / Unknown -> Replay or Reconcileseparates execution rights from response reuse. Only a failure before execution releases the reservation, and an unknown outcome goes to reconcile.In domains where duplicate execution is expensive, such as payments, orders, and reservations, an in-memory store will not do; you need a durable store, a unique constraint, and an atomic
ON CONFLICTupsert.Domain conflicts, key misuse, and infrastructure failures each need their own response policy and their own metrics.
Never put sensitive data in an idempotency key, and design the tenant/account scope and the TTL policy together.
Quick mnemonic:
To safely retry a POST, design the key, fingerprint, durable replay, and failure release together.Personal note: Idempotency is usually taught as "preventing duplicate requests," but in practice it means "safely handling duplicate requests while cleanly resolving failed ones."
Footnotes
- IETF. RFC 9110: HTTP Semantics (idempotent methods) ↩
- IETF. The Idempotency-Key HTTP Header Field (draft-ietf-httpapi-idempotency-key-header) ↩
- Stripe. Idempotent requests ↩
- IETF. RFC 8941: Structured Field Values for HTTP (Idempotency-Key header format) ↩
- Python. threading — Lock objects ↩
- IETF. RFC 8785: JSON Canonicalization Scheme (JCS) ↩
- PostgreSQL. INSERT ... ON CONFLICT (upsert) ↩