Idempotency key
An idempotency key is a unique, client-generated value sent with an API request so the server can recognize retries of the same operation and execute it only once. When the same key arrives again — after a timeout or dropped connection — the server returns the original result rather than repeating the side effect, making operations like payments and order creation safe to retry.
Agents retry by design. An unattended agent that sends a POST, hits a timeout, and reattempts has no way to know whether the first request succeeded — without idempotency support, that retry can double-charge a card or create a duplicate record. Idempotency keys are the mechanism that makes automated retry loops safe on non-idempotent operations.
The mechanism only works if it is documented where an agent will find it: which header carries the key (commonly `Idempotency-Key`), which endpoints honor it, how long the server remembers a key, and what happens on a key conflict. An agent cannot infer any of this from the wire; it acts on what the docs state.
APIs that pair documented idempotency semantics with documented retry guidance give agents a complete, safe failure-recovery loop — each half is weaker without the other.
Discry records whether idempotency behavior is documented as one of the execution-documentation facts on an API's profile ('Idempotency documented'), alongside rate limits, pagination, and error format. These are check-level facts about the public docs surface — Discry does not execute authenticated calls or test the retry behavior itself.
What does an AI agent make of your API?
Find out in about a minute — no signup.
Discry your API — free