Idempotency Keys: How APIs Handle Duplicate Requests Without Double-Charging

When a network drops a connection mid-request, clients must retry — but servers risk executing the same operation twice, such as charging a card or creating duplicate orders. Idempotency keys solve this by having clients attach a unique token (typically a UUID) to every retry of the same logical operation, allowing servers to detect and deduplicate repeated requests. A naive database check for existing keys introduces a race condition, where two concurrent retries can both pass the cache check and trigger the side effect twice. The correct approach is to atomically claim the key before executing any work, using database-level conflict handling to ensure only one request proceeds. Servers must then explicitly handle three states — in-progress, completed, and failed — each requiring a distinct response strategy to ensure reliability under real-world network conditions.