Idempotency Scope
The boundary within which an idempotency key is unique and meaningful — per account, per endpoint, or global — and the retention window it lives for.
Two decisions that determine whether the guarantee actually holds.
Scope. Keys are normally scoped per API key or account, so one customer cannot collide with or observe another's. A global scope leaks information and creates cross-tenant collisions; a per-endpoint scope means the same key on a different endpoint is a different operation, which is usually what you want but must be stated.
Retention. The record must outlive any plausible retry — a client retrying after a deployment, a queued job redelivered hours later, a mobile client that was offline. Twenty-four hours is a common floor; shorter windows silently reintroduce duplicates in exactly the cases the mechanism exists for.
Also specify what happens on key reuse with a different payload: it means the client has reused a key for a different operation, and the correct response is an error rather than either processing it or returning the old result.