Error Handling Patterns

Error Strategy Decision Table

Recoverability Framework

Can the caller realistically recover?
├── Yes → Use explicit signaling (Result type, checked exception)
│   ├── Expected failure (not found, validation) → Return type encodes the failure
│   └── Transient failure (timeout, rate limit) → Retry with backoff
├── No → Let it propagate (unchecked exception, panic)
│   ├── Bug → Crash and fix the code
│   └── Infrastructure failure → Propagate to top-level handler
└── Caller determines → Provide both options (Result + throw helper)

Signaling Comparison Table

Error-Hiding Antipatterns

Strategy Selection Flowchart

What kind of code are you writing?
├── Public API / library
│   ├── Caller must handle → Checked exception or Result type
│   └── Caller can't handle → Unchecked exception (document it)
├── Internal service code
│   ├── Expected failure → Result type
│   └── Bug / unexpected → Let it propagate
├── Hot path (measured)
│   └── Error codes or Result types (avoid exception overhead)
└── Script / CLI
    └── Crash with clear message (fail fast)

Checklist

Before shipping error handling code:

• Every catch block either recovers, propagates, or fails explicitly
• No empty catch blocks
• "Not found" and "system failure" use different error channels
• Error messages are actionable (what happened, what to do)
• Third-party exceptions wrapped in domain types at boundaries
• Error paths have test coverage