Idempotency

Idempotency is the property where performing an operation multiple times produces the same end-state as performing it once. The first call applies the change; subsequent calls with identical input are safely absorbed without producing duplicates, side effects, or errors. In API terms, an idempotent endpoint can be retried without fear that retrying will charge a customer twice, create two orders, or send the same email five times.

The standard implementation pattern is the idempotency key: the client generates a unique ID for the operation (often a UUID) and sends it as a header like Idempotency-Key. The server stores a record of (key → result) on first call; on retry with the same key, it returns the stored result instead of re-executing the work. Stripe, GitHub, and most modern payment APIs use this pattern.

HTTP semantics already give you idempotency for free on GET, PUT, and DELETE — those methods are defined as idempotent by spec. POST is not, which is why idempotency keys are critical for POST endpoints that create resources. Without idempotency, every network blip, gateway timeout, or client retry becomes a data integrity bug waiting to happen.