Error Recovery & Retry Patterns

Effective error recovery requires distinguishing error types and applying the right recovery strategy for each.

Retryable vs Non-Retryable Errors

Returning structured metadata with isRetryable prevents wasted retry attempts:

Business Rule Violations

For business errors, include:

• retriable: false to prevent pointless retries
• A customer-friendly explanation the agent can relay to the user
• Suggested alternative actions (e.g., "escalate to manager" or "split into smaller amounts")

Local vs Propagated Recovery

Subagents should handle transient failures locally:

1. Retry timeouts with backoff (2-3 attempts)
2. Try fallback data sources if primary is unavailable
3. Proceed with partial results and annotate gaps

Propagate to the coordinator only when:

• Local recovery has been exhausted
• The error requires a decision beyond the subagent's scope
• Always include: what was attempted, partial results, and the unresolvable failure

Access Failures vs Valid Empty Results

This distinction is critical and commonly confused:

• Access failure (database timeout): The query did not complete -- retry is appropriate
• Valid empty result (0 matches found): The query succeeded -- do not retry

Treating an access failure as an empty result means missing data. Treating an empty result as a failure wastes retries and may cause incorrect escalation.