1---
2name: error-handling
3description: Use when designing error hierarchies, implementing React error boundaries, adding retry logic or fallbacks, creating API error responses, integrating error tracking (Sentry), or improving user-facing error communication.
4---
5
6# Error Handling
7
8Design resilient applications through intentional error handling strategies. Errors are data, not just exceptions — design them intentionally.
9
10## Quick Decision Guide
11
12| Situation | Pattern | Reference |
13|-----------|---------|-----------|
14| Typed error categories | Custom error classes | [error-patterns.md](references/error-patterns.md) |
15| Explicit handling (no throws) | Result/Either type | [error-patterns.md](references/error-patterns.md) |
16| React component crash | Error boundary | [react-errors.md](references/react-errors.md) |
17| API error response | Structured API errors | [api-errors.md](references/api-errors.md) |
18| Network calls that fail | Retry with backoff | [recovery-patterns.md](references/recovery-patterns.md) |
19| Unreliable downstream service | Circuit breaker | [recovery-patterns.md](references/recovery-patterns.md) |
20
21## Key Principles
22
23- **Debuggable**: Rich context, stack traces, correlation IDs
24- **Recoverable**: Retry logic, fallbacks, circuit breakers
25- **User-friendly**: Clear messages, recovery guidance, no leaked internals
26- **Consistent**: Same error shape across all API endpoints
27
28## Quick Start Checklist
29
301. Define base AppError class with code and context
312. Create domain-specific error subclasses
323. Implement consistent API error response shape
334. Add error boundaries at app, route, and component levels
345. Set up error tracking (Sentry) with scrubbing
35
36## References
37
38| Reference | Description |
39|-----------|-------------|
40| [error-patterns.md](references/error-patterns.md) | Custom errors, Result types, error hierarchies |
41| [react-errors.md](references/react-errors.md) | Error boundaries, Suspense, React error handling |
42| [api-errors.md](references/api-errors.md) | HTTP errors, response shapes, status codes |
43| [recovery-patterns.md](references/recovery-patterns.md) | Retry, circuit breaker, fallbacks, degradation |
44| [overview.md](references/overview.md) | Error types, Result pattern, user messages, tracking, anti-patterns |
45| [anti-rationalization.md](references/anti-rationalization.md) | Iron Law, common rationalizations, red flag STOP list for error handling discipline |
46| [tdd-patterns.md](references/tdd-patterns.md) | Test-first patterns for error paths, retry logic, boundaries |
47| [review-checklist.md](references/review-checklist.md) | Error handling review checklist (classes, messages, recovery, tracking) |
48
49## Runtime Notes
50
51- **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>"`.
52- **Codex**: there is no subagent dispatch. Execute the agent's role inline — read the corresponding `agents/yokay-<name>.md` and follow its Behavioral Defaults, Critical Rules, and Output Contract directly in the current session.
srstomp