Idempotency key

An idempotency key is a client-supplied identifier that a supporting service uses to recognize retries of the same intended operation within a defined scope and retention window.

The client reuses one key for retries of one logical operation. A service may return the stored result, report that processing is still underway, or reject the key if request parameters differ. Keys expire and are scoped by provider rules, so they do not create permanent global exactly-once execution.

Builder example

Retries are normal in any agent that talks to outside services, because a timeout often means the request went through but the reply got lost. If your agent charges a card, books a slot, or posts a message, a blind retry can double the action and the user feels the mistake directly. Tell your agent to attach a stable idempotency key to each action that has a side effect, and reuse the same key when it retries rather than minting a fresh one.

Common confusion: An idempotency key works only when the receiving service is built to honor it and store recent keys. The key is a request you make of the service; if that service ignores the header or has no memory of past keys, sending one changes nothing and the duplicate still goes through.