Idempotency & Retries

A retry must not do it twice

A timeout does not tell you whether the work happened. The request may have completed and the response been lost. Retrying is usually the only option available, so the receiving side has to make a repeat harmless.

The standard mechanism is a key the caller generates and sends with the request. The service records it; if the same key arrives again it returns the original result rather than doing the work a second time.

This matters more with agents than with ordinary software, because an agent will retry on its own initiative, in a loop, with no human deciding whether that is wise. Any tool with a side effect — sending, charging, deleting — needs this before an agent is allowed near it.