---
title: "Best Practices"
description: "Compensations might run more than once (retries). They should produce the same result regardless. Each step should do one thing. Don't combine multiple operations in a single step. Your compensation code is as important "
resource: https://www.aiagents.nexus/docs/manual/sagas/best-practices
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# Saga Best Practices

## 1. Make Compensations Idempotent

Compensations might run more than once (retries). They should produce the same result regardless.

```
# ✓ Good: Idempotent refund
refund(orderId) → if not already refunded, refund

# ✗ Bad: Non-idempotent
refund(orderId) → always issue refund (double refund!)
```

## 2. Keep Steps Small

Each step should do one thing. Don't combine multiple operations in a single step.

## 3. Test the Rollback Path

Your compensation code is as important as your forward code. Test it thoroughly.

## 4. Use Checkpoints for Long Sagas

For sagas with many steps, checkpoints prevent re-running completed steps after a crash.

## 5. Monitor Saga Executions

```bash
naos saga status --all
naos audit --filter saga
```

## 6. Handle Compensation Failures

Have a plan for when compensations fail. Manual resolution should be documented.

## 7. Set Timeouts

Don't let saga steps run forever:

```yaml
sagas:
  order:
    timeout: 300    # 5 minutes total
    stepTimeout: 60 # 1 minute per step
```