error-handling-patterns

Error Handling Patterns

Design error handling strategies that make failures explicit, recoverable, and debuggable. The central skill is matching error handling style to error semantics: not all errors are equal, and treating them equally produces systems that are equally bad at handling all of them.

When to Use

✅ Use for:

• Choosing between exceptions, Result types, or error codes for a domain
• Designing typed error hierarchies in TypeScript or Python
• Implementing retry logic with backoff, jitter, and circuit breaking
• Building React error boundaries and graceful degradation
• Structuring error information for both users and developers
• Python exception chaining and __cause__ / __context__ semantics

❌ NOT for:

• Debugging a specific runtime error (use debugger or domain skill)
• Logging pipeline infrastructure (use observability skill)
• APM/monitoring configuration (use site-reliability-engineer skill)
• Writing tests for error paths (use vitest-testing-patterns skill)

---

Core Decision: Exception vs Result Type vs Error Code

flowchart TD
    Q1{Is this a programming error\nor contract violation?} -->|Yes| EX[Throw exception\nlet it crash]
    Q1 -->|No| Q2{Is the error part of\nnormal control flow?}
    Q2 -->|Yes| Q3{What is the call site context?}
    Q2 -->|No| Q4{Do callers need to\ndistinguish error types?}
    Q3 -->|Functional / monad-friendly| RT[Result or Either type]
    Q3 -->|Simple script or CLI| EC[Error code + message]
    Q4 -->|Yes| EH[Typed exception hierarchy]
    Q4 -->|No| GE[Generic exception\nwith structured message]
    EX --> NOTE1[Never catch at boundary —\nlet process restart]
    RT --> NOTE2[Compose with map/flatMap;\ncheck references/error-hierarchy-examples.md]
    EH --> NOTE3[See hierarchy design rules below]

Rules of thumb:

• Library code: prefer Result types — never force callers to handle your exceptions
• Application code: typed exception hierarchies work well; errors are exceptional
• CLI / scripts: error codes are fine; the user is the error boundary
• Async workers: Result types or structured error objects with retry metadata