Error Handling
Design resilient applications through intentional error handling strategies. Errors are data, not just exceptions — design them intentionally.
Quick Decision Guide
| Situation | Pattern | Reference |
|---|---|---|
| Typed error categories | Custom error classes | error-patterns.md |
| Explicit handling (no throws) | Result/Either type | error-patterns.md |
| React component crash | Error boundary | react-errors.md |
| API error response | Structured API errors | api-errors.md |
| Network calls that fail | Retry with backoff | recovery-patterns.md |
| Unreliable downstream service | Circuit breaker | recovery-patterns.md |
Key Principles
- Debuggable: Rich context, stack traces, correlation IDs
- Recoverable: Retry logic, fallbacks, circuit breakers
- User-friendly: Clear messages, recovery guidance, no leaked internals
- Consistent: Same error shape across all API endpoints
Quick Start Checklist
- Define base AppError class with code and context
- Create domain-specific error subclasses
- Implement consistent API error response shape
- Add error boundaries at app, route, and component levels
- Set up error tracking (Sentry) with scrubbing
References
| Reference | Description |
|---|---|
| error-patterns.md | Custom errors, Result types, error hierarchies |
| react-errors.md | Error boundaries, Suspense, React error handling |
| api-errors.md | HTTP errors, response shapes, status codes |
| recovery-patterns.md | Retry, circuit breaker, fallbacks, degradation |
| overview.md | Error types, Result pattern, user messages, tracking, anti-patterns |
| anti-rationalization.md | Iron Law, common rationalizations, red flag STOP list for error handling discipline |
| tdd-patterns.md | Test-first patterns for error paths, retry logic, boundaries |
| review-checklist.md | Error handling review checklist (classes, messages, recovery, tracking) |
Runtime Notes
- Claude Code: dispatch the relevant agent (yokay-implementer, yokay-fixer, yokay-spec-reviewer, or yokay-quality-reviewer) via the Task tool with
subagent_type: "pokayokay:yokay-<name>". - Codex: there is no subagent dispatch. Execute the agent's role inline — read the corresponding
agents/yokay-<name>.mdand follow its Behavioral Defaults, Critical Rules, and Output Contract directly in the current session.