Saga compensation design
Give maintainers a map of partially completed states
Operators need to know which effects exist, which remain uncertain and who can resolve them. Transfer that map with the coordinator code.
In this article
Describe states in business terms
For each meaningful partial state, list completed effects, unresolved operations and permitted next actions. A status such as compensationFailed should link to the particular reservation, payment or booking still needing attention.
Keep the technical state machine, but add the business interpretation operators require. They should not need to read orchestration code during an incident to discover what might still be active.
Record irreversible conditions and the owner of the manual decision path. Those cases are part of normal operating responsibility even if they are rare.
Transfer identifiers and recovery tools
Provide a way to trace the saga into every participating service using stable operation references. Explain which lookups establish confirmed state and which provide only partial evidence.
Document retry and replay semantics for forward and compensating calls. Include retention limits and the procedure for old unresolved operations.
Keep manual tools scoped and audited. Operators need supported actions that preserve the state trail, not instructions to edit status flags until the dashboard turns green.
Rehearse partial recovery
Have the receiving team resolve a failed forward step, then a failed compensation and an uncertain correction. Use synthetic services or controlled test records.
Ask them to verify the final business state across dependencies and explain it to a requester. This checks whether the documentation supports the actual outcome rather than only advancing the coordinator.
Test coordination with automated workers so manual intervention cannot race with a delayed retry.
Assign ongoing ownership
Name who monitors aged unresolved states, who owns each service's correction contract and who coordinates cross-service incidents. Version changes need an owner for already active sagas as well as new ones.
Review recurring manual cases for opportunities to improve evidence, step order or service contracts. Keep the fixture library current when business rules change.
The handover succeeds when maintainers can identify what has happened, choose an authorised next action and preserve a truthful record of recovery. Partial completion should be an understood operating state, not knowledge held only by the workflow's original author.
Primary sources
Microsoft Learn: compensating transactionsOWASP: logging guidanceReferences checked 11 September 2026.