What is Retry policy?
Also called retry strategy, retries.
A retry policy defines when a failed operation is attempted again, how many times, how long to wait between attempts, and which failures are eligible. Transient failures such as timeouts and rate limit rejections are usually retried, while validation errors and permission denials are not. Without a bounded policy, retries can multiply load and turn a small fault into an outage.
A policy has four parts: a rule for which errors are eligible, a maximum number of attempts, a delay strategy between them, and an overall deadline for the whole operation. Timeouts, connection failures, rate limit rejections, and explicit server errors are typically eligible. Malformed input, permission denials, and not found responses are not, because repeating them produces the same answer while consuming capacity.
Retries matter because transient failure is normal in any system that crosses a network, and agent runs cross several per step. A single well-placed retry converts most brief network problems into invisible delays. The alternative, surfacing every transient error to the user or to the agent's own reasoning, produces unreliable behavior and unnecessary restarts of expensive work.
The dangerous mistake is retrying an operation with side effects that are not idempotent, which duplicates messages, payments, or records. The second is layering retries at several levels, where three attempts in a client inside three attempts in a wrapper inside three at the caller produces twenty-seven calls from one request. The third is retrying without a total deadline, so a request outlives the user waiting for it.
Retry policy, exponential backoff, and idempotency form a set that only works together. Backoff decides how long to wait, idempotency makes the repeat safe, and a circuit breaker decides when to stop trying at all. Anything that exhausts its attempts should land somewhere durable, such as a dead letter queue, rather than disappearing into a log line.
Key points
- Retry transient failures only; validation and permission errors are terminal.
- Bound attempts and total time, not just attempt count.
- Retrying a non-idempotent call can duplicate real side effects.
- Layered retries multiply: allow retries at one level only.
In practice
An agent sends a customer email through a provider that returns a timeout. The provider actually delivered the message, but the response was lost. A naive policy retries three times and the customer receives four identical emails. Adding an idempotency key so the provider recognizes the repeat, and capping the attempts, keeps the delivery guarantee while removing the duplicates.