Idempotency: The Foundation of Reliable Financial APIs

Retries make idempotency a financial requirement

Networks duplicate requests: clients retry after timeouts, gateways replay, workers redeliver, and users press submit again. In a financial API, “probably once” is not acceptable. Idempotency gives multiple deliveries of the same logical command one authoritative outcome.

Choose the operation identity

Use a caller-provided idempotency key scoped to account/tenant and operation type.
Persist key, request fingerprint, status, and result in durable storage.
A reused key with a different request body is a conflict, not a duplicate success.
Acquire the key atomically before executing irreversible effects.
Return the stored response for a completed duplicate; define behavior for an in-progress duplicate.

First request and duplicate request paths

The key is checked and reserved before business execution; later retries observe the same durable result instead of executing the transfer again.

Diagram

Duplicate-safe payment command

The key is checked and reserved before business execution; later retries observe the same durable result instead of executing the transfer again.

POST + idempotency key

Atomic key reservation

Validate fingerprint

Execute payment

Store response

Retry returns stored result

A payment creation example

A unique key is the concurrency guard

The database uniqueness constraint prevents two workers from owning the same logical command.

CREATE TABLE api_idempotency (
  tenant_id text NOT NULL,
  operation text NOT NULL,
  idem_key text NOT NULL,
  request_hash text NOT NULL,
  status text NOT NULL,
  response_ref text,
  PRIMARY KEY (tenant_id, operation, idem_key)
);

False idempotency patterns

Idempotency implementation checklist

Define key scope and retention period.
Store a canonical request fingerprint.
Make key reservation atomic with concurrency protection.
Persist final status and response reference.
Load-test concurrent duplicates and simulate lost responses.