What Is an Idempotency Key?
An idempotency key is a unique token attached to a request so the server can recognise a repeat. If the same key arrives twice, the server returns the original result instead of performing the action again.
Duplicates are not a rare edge case with forms. People double-click submit. A flaky connection retries after the request already succeeded. A client library retries on a timeout that happened after the write. Each produces two identical submissions that a human then has to reconcile.
The key has to come from the client and stay stable across retries, which is what separates it from a server-generated id. A value generated fresh on every attempt defeats the purpose entirely.
Servers keep these keys for a bounded window, typically hours rather than forever, which is long enough to cover retries and short enough that storage stays finite.