Idempotency in API Design
Term 55 of 68 in the ERPStack technical glossary
What is Idempotency in API Design?
Idempotency is the API design principle where making the same HTTP request multiple times produces identical server state — critical for financial transactions and payment APIs where network failures can cause duplicate requests.
Idempotency in API Design at a glance
- Definition
- N identical requests produce the same state as 1 — the standard's own definition in RFC 9110
- By specification
- GET, HEAD, PUT and DELETE are idempotent; POST is not (RFC 9110, June 2022)
- Mechanism
- A client-generated idempotency key stored with the result; a replay returns the original response
- Why it matters
- A timeout is ambiguous — without a key, 1 retry can create 2 payments
- Built with
- Idempotency keys stored in PostgreSQL 18 through Drizzle ORM 0.45 or Redis, enforced in Next.js 16 route handlers, replays surfaced in Sentry and traced with OpenTelemetry
- Numbers that matter
- RFC 9110 marks 4 methods idempotent; 24 hours is a safe key retention default; 1 effect per key; 2 writes that must share 1 transaction
- Where it applies
- REST endpoints, a GraphQL API Schema, webhooks and Apache Kafka consumers
- Commonly paired with
- Redis or PostgreSQL 18 key storage through Drizzle ORM 0.45, Apache Kafka consumers, Next.js 16 route handlers, a GraphQL API Schema or REST surface, Sentry replay alerts and OpenTelemetry Observability traces
- Where it is enforced
- Next.js 16 route handlers, Apache Kafka consumers, webhook receivers and REST endpoints — 4 surfaces sharing 1 key store in Redis or Postgres, with Zod 4 validating the key and Vitest 4 proving a replay changes nothing.
How Idempotency in API Design works in production
The ERPStack approach to Idempotency in API Design
We implement idempotency key tables in PostgreSQL with ON CONFLICT DO NOTHING semantics for all payment, payout, and inventory mutation API routes — as demonstrated in an artisan-manufacturing ERP build where 118 idempotent API routes eliminated all payout duplication errors.
Frequently asked questions about Idempotency in API Design
What does Idempotency mean in API Design?
That repeating a request does not change the outcome. Idempotency in API Design matters because networks fail ambiguously: a client that times out cannot tell whether the server processed the request or never received it. RFC 9110, the June 2022 HTTP semantics standard, defines GET, HEAD, PUT and DELETE as idempotent, while POST is not — which is exactly why POST endpoints need explicit protection.
How do idempotency keys work?
The client generates a unique key per logical operation and sends it with the request. The server stores the key with the result of the first execution. On a replay, Idempotency in API Design requires the server to recognise the key and return the stored response instead of executing again. The key must be stored in the same transaction as the effect, or a crash between the 2 writes reopens the hole.
Why can't you just retry safely without this?
Because at-least-once delivery is the norm, not the exception. Message queues redeliver, clients retry, and load balancers replay. Without Idempotency in API Design, each of those produces a duplicate charge, a duplicate order or a doubled stock movement. The failure is invisible in testing, where nothing times out, and appears in production during exactly the incidents you least want compounded.
How long should idempotency keys be retained?
Long enough to outlive the client's retry window, which is usually hours rather than seconds. Idempotency in API Design breaks if the key expires before the last retry arrives, because the replay then executes as a fresh request. A 24-hour retention with the key stored beside the operation result is a common, safe default, and the storage cost is trivial next to a duplicate payment.