Idempotency

Idempotency is the property that repeating an operation produces the same outcome as performing it once. An idempotent operation can be safely retried after a network failure, timeout, or partial failure, without risking duplicate side effects.

Idempotency by HTTP method

• GET, HEAD, OPTIONS: safe and idempotent by definition
• PUT, DELETE: idempotent (replacing or removing the same resource repeatedly has the same final state)
• POST: not idempotent by default; APIs that need it expose an idempotency key
• PATCH: idempotent only if the patch is absolute, not delta-based

Idempotency keys

The standard pattern for making POST safe to retry: the client supplies a unique key (typically a UUID) in an Idempotency-Key header. The server stores the response keyed by that ID. Retries with the same key return the original response instead of executing the operation again. Stripe, Square, and most modern payments APIs use this pattern.