What Is Idempotency? A Practical Guide for API Developers

Idempotency means running the same operation multiple times produces the same server-side effect as running it once. It's how you prevent double charges, duplicate webhook processing, and repeated queue message handling. GET, PUT, and DELETE are idempotent by definition per RFC 9110. POST is not.

The idempotency key pattern (popularized by Stripe) has clients send a unique key with each request. On replay, the server returns the stored response instead of re-executing. If the same key arrives with different parameters, the server returns a 409 Conflict. The real enforcement happens at the database level: a UNIQUE constraint on the key column guarantees atomicity where application-level check-then-insert logic fails to a TOCTOU race.

If you're building payment endpoints, webhook handlers, or queue consumers, make idempotency your default. Don't rely on dedup windows or exactly-once delivery promises. Design for at-least-once and let the constraint catch duplicates.