Common mistakes include confusing “safe to retry” with “no side effects”; idempotency concerns the final state, not the number of attempts.

Final rule: any operation that might be retried must be idempotent; non-idempotent retry logic is a bug that can cause money loss, data corruption, and erode customer trust.

In REST APIs, different HTTP methods have distinct guarantees: GET is safe to retry and read-only, POST is not idempotent without safeguards, PUT and DELETE are idempotent, and PATCH is usually not idempotent unless it replaces a value.

Idempotency means an operation yields the same end state whether it runs once or multiple times, making retries safe in the presence of failures.

Practical guidance: always consider idempotency for mutating endpoints, wrap non-idempotent tool calls in idempotency mechanisms, and use transactions or idempotency keys to prevent duplicate effects in agents and automation.

A concrete example is using an idempotency key with POST /api/orders; the server returns the previous result if the key has been seen, otherwise it processes the request and records the outcome.

Three main scenarios where idempotency matters: mutating APIs, agents/automation calling tools, and integrations with other systems; verify safety by explicit repeat-testing of the operation and outcome.

The real-world problem is retries after partial failures, which can cause duplicate charges or data corruption; idempotency keys help ensure repeated requests produce the same outcome by storing and reusing the original response.

Testing approach: perform an operation, record its result, retry the same operation, and confirm identical results; if not identical, the system isn’t idempotent and retrying is dangerous.