Idempotency key

The problem is that a client cannot distinguish "the request never arrived" from "the request succeeded but the response was lost". Both look like a timeout, and both invite a retry. With an idempotency key the server can tell the difference: it records the key with the outcome, and a second request carrying the same key returns the stored response rather than executing again.

Scope and lifetime need to be defined explicitly. A key is normally meaningful within one account and one endpoint, so the same string on a different operation is a different key. The retention period bounds how long a retry is recognised — long enough to cover realistic retry behaviour, short enough that storage does not grow without limit.

Keys must be generated per logical operation, not per attempt. A UUID minted fresh on every retry provides no protection at all, which is the most common way the mechanism is defeated in practice. The key belongs to the intent — this specific call to this specific person for this campaign — and travels unchanged across every attempt to fulfil it.