With idempotency keys, scope and retention matter more than length
When the same payment or order request arrives twice because of a network retry, it is processed twice. An idempotency key prevents that: it is an identifier the client generates for each request. If the server generated it, the client could not resend the same key on a retry, which defeats the purpose. Enter your request rate, retention window and key format to get the number of stored keys, the collision chance and the storage needed.
Keys are usually stored under a scope that combines the endpoint with the key, and a repeat of the same key returns the stored response instead of processing the work again. If the same key arrives while the first request is still in flight, a lock or a unique constraint has to let only one through. Standardising the idempotency key as an HTTP header is still under discussion rather than settled, so the header name and behaviour belong in your own API documentation. Current as of October 2026.
There is no official recommended key length or retention window, so this page suggests none and only reports what your format produces. The collision chance assumes keys are uniformly random and does not model bias in a real generator. Choosing a key store and implementing the duplicate check itself are not supported.
Frequently Asked Questions
Rejecting it with 409 instead of processing it is the widely used approach. The same key is a promise that it is the same request, so a different body usually means the client reused a key by mistake.
If the server generates it, the client cannot send the same key on a retry, so duplicates are not prevented. The client has to generate one key per request and reuse it on every retry.
There is no official recommended window. The benchmark is that it outlasts the point where clients stop retrying, and entering a window here gives the key count and storage for that period.