Idempotency
A property where performing an operation multiple times has the same effect as performing it once.
Idempotency
Idempotency is a property of an operation where performing it more than once produces the same result as performing it exactly once. In the context of an API, an idempotent request can be safely retried: if a client sends the same request twice, whether by accident or as a deliberate retry after a network failure, the outcome is no different from having sent it a single time.
How it works
Some operations are naturally idempotent. Reading a resource does not change anything, so repeating the read is harmless. Setting a resource to a specific value is also idempotent, since sending the same update twice leaves it in the same final state either time. Other operations, particularly creating a new resource, are not idempotent by default: submitting the same creation request twice would normally create two separate resources. APIs commonly make such operations idempotent by accepting a client-supplied idempotency key, a unique identifier attached to the request; the server records which keys it has already processed and, if it sees the same key again, returns the result of the original operation instead of performing it a second time.
Why it matters for AI agent systems
Networks are unreliable, and a client cannot always tell whether a request that appears to have failed, such as one where a response was never received, actually reached the server and was processed. For most operations the safe response is to retry, but retrying a task submission without idempotency protection risks running the same task twice, which for an AI agent can mean duplicate work, duplicate side effects such as sent messages or modified files, and duplicate consumption of paid upstream LLM API calls. Idempotency keys let a client retry a task submission safely, confident that the agent will run the task once even if the request was technically sent more than once.
Idempotency and self-hosted platforms
Idempotency matters even more on self-hosted infrastructure, where the operator, rather than a managed vendor, is responsible for handling edge cases like retries and network interruptions correctly. An operator building automation on top of an agent platform's API needs to know which operations are safe to retry blindly and which require an idempotency key or other safeguard to avoid submitting the same task more than once.