CORE GUIDE
Compensation and recovery
Compensation and recovery handle workflows where an earlier side effect succeeded but a later step failed, using reconciliation, compensating actions and durable state instead of pretending the whole transaction can simply be retried.
Mental model
A distributed workflow is often a saga rather than one atomic transaction. Recovery asks what actually happened; compensation applies a domain-specific action that restores an acceptable business state when true rollback is impossible.
Why it matters
Agents call external systems that do not share one transaction boundary. A payment may succeed before email fails, a reservation may be created before the next tool times out, or a cancellation may race with completion. Blind retry can duplicate side effects, while naive rollback may be impossible.
01
Reconcile first, compensate second
Persist an operation identifier and each confirmed side effect. On failure or timeout, query authoritative systems to determine the real state before deciding what to retry. If an irreversible step completed, run a defined compensating action such as refund, release or reversal, and make that action idempotent as well. Escalate when the domain cannot safely restore state automatically.
02
Example: booking succeeds but confirmation times out
An agent reserves a hotel room, then the confirmation API times out. Retrying the full workflow can create a second reservation. Recovery checks the reservation provider with the original idempotency key, finds the booking, records it as completed and retries only the notification. If a later policy check fails, the system executes the explicit cancellation compensation.
Common failure modes
- Retrying the entire workflow before discovering which side effects actually completed.
- Calling compensation 'rollback' when the external system cannot restore the exact prior state.
- Designing the forward path without durable operation identifiers or recovery state.
Engineering heuristics
- Persist side-effect state and idempotency keys before moving to later steps.
- Reconcile authoritative external state before choosing retry or compensation.
- Treat compensation as explicit domain behavior with its own failure handling.
Takeaways
- 01Recovery begins by establishing what really happened.
- 02Compensation is not the same as database rollback.
- 03Durable state and idempotency make partial failure manageable.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.