Idempotency & Compensation
Can this action be retried safely, and what happens after a partial failure?
Reference notes by Min · Reviewed October 15, 2026
Definition
Idempotency makes repeated execution of the same logical operation avoid additional effects. Compensation uses a new, explicit action to address a previously completed step when a wider workflow fails; it may not restore the original state exactly.
Agents work through fallible services and may retry when a response is missing. The decision to retry must distinguish an unknown result from a confirmed failure. The business operation, its parameters, and the service’s actual contract determine what is safe.
What it covers
- Operation identity
- Identify one intended business operation across retries.
- Duplicate handling
- Define service behavior for repeated or conflicting requests.
- Partial state
- Record which steps actually committed.
- Recovery authority
- Determine who may reconcile, compensate, or escalate.
A single task may contain several operations with different identities and effects. Preserve their relationships and committed outcomes. A parent task ID is useful for correlation but should not be assumed to be a sufficient idempotency key for every downstream service.
In practice
Practical design patterns by Min.
- Use the service’s supported idempotency mechanism for consequential calls.
- Keep the same operation identity for a true retry, with the same intended parameters.
- Reconcile uncertain outcomes before issuing a replacement transaction.
- Design and authorize compensating actions separately from the original operation.
Confirm the service’s key scope, retention window, and response to changed parameters. Those details matter when a delayed response arrives or a worker resumes after interruption. Test the behavior instead of assuming that an “idempotent” label covers every retry pattern.
Working example
An uncertain purchase response
A purchase API times out after an agent submits an approved order.
- Look up the operation or retry through the supported idempotency contract.
- Confirm whether the order exists before creating a different operation.
- If a later step fails, follow the approved cancellation or recovery procedure and record the resulting state.
Why the controls matter
The purchase can have succeeded even though the agent saw a timeout. Recovery first establishes the service state; it does not automatically repeat payment. A cancellation or refund may require additional approval and can introduce its own operational consequences.
Common pitfalls
- Treating a timeout as proof that the transaction failed.
- Generating a new idempotency key for every retry.
- Assuming compensation can unsend a message or perfectly reverse every effect.
Compensation is a new business action with its own permissions and failure modes. It may require manual intervention and cannot erase information already delivered externally. Preserve an audit record of the original action and the recovery.
Questions for operational review
Use these questions to decide what evidence your team needs. They are editorial prompts, not a compliance checklist.
- How is one logical operation identified?
- What proves a side effect committed?
- Who may authorize compensation or manual recovery?
Articles linking here
- Runtime Governance
- Audit Trail
- Multi-Agent Security
- Agent Change Management
- Staged Agent Rollout
- Browser Agent Governance
- Agent Decommissioning
- Agent Output Validation
- Task Deadlines & Cancellation
- Retry Budgets & Backoff
- Concurrency Control for Agents
- Transactional Outbox for Agent Actions
- Designing Reliable Tools for Agents
- Durable Execution, Checkpoints & Recovery
References
Primary documents reviewed for this entry. Examples and implementation patterns are editorial synthesis.
- Amazon Builders’ Library: Making retries safe with idempotent APIs ↗Accessed October 15, 2026
- Microsoft Azure Architecture Center: Compensating Transaction pattern ↗Accessed October 15, 2026