Devii · APIs & integration · 2026-02-12 · 6 min read
Idempotency Keys For `POST`: How Stripe-Style APIs Avoid Duplicate Side Effects
A standards-grounded pattern: safe retries without assuming `POST` is automatically idempotent.
HTTP defines `GET`, `PUT`, and `DELETE` as idempotent methods; `POST` is not guaranteed to be idempotent (see RFC 9110 semantics). Payment and billing APIs therefore use client-supplied idempotency keys so retries after timeouts do not double-charge.
A minimal server design stores `(key, route, actor) -> response outcome` for a TTL window, returns the same status/body for duplicates, and rejects conflicting replays. Keys should be unguessable (UUIDs) and scoped per integration environment.
Clients should send the same key on intentional retries only, not on unrelated operations. Combine with structured error codes so mobile and web clients know when a retry is safe.