error-handling

When to use

• Designing how errors propagate across layers for a new feature or service boundary
• Choosing retry, circuit-breaker, or fallback strategy for calls to external systems
• Establishing throw-vs-return conventions for a module or codebase
• Mapping internal errors to user-facing messages at an edge boundary

Not for: diagnosing a specific bug or test failure (use debugging); system-level resilience architecture — cross-service error strategy, overall failure posture (use architecture, specifically architecture/references/error-resilience.md); API error response envelope shape (use api-design); production logging/metrics instrumentation (use observability).

Steps

For system-level resilience architecture (cross-service error propagation, failure posture design), read architecture's error-resilience reference first. This skill is the implementation-level companion — the decisions you make at the keyboard when writing the error-handling code.

1. Classify errors

Every error falls into one of four categories, and the category drives the strategy:

Category	Examples	Strategy
Transient	network timeout, 503, connection reset	retry with backoff (step 3)
Permanent	404, 400, logic failure	fail fast, no retry
Validation	bad input, schema mismatch	return 422-style result to caller
Auth	expired token, insufficient scope	return 401/403, prompt re-auth

If you can't classify an error, default to permanent — retrying an unclassified error masks real bugs.

2. Choose throw-vs-return convention

Pick one convention per layer and enforce it (architecture ref §1 has the full rationale):

• Throw (exceptions) for invariant violations and infrastructure failures — "this should never happen, the operation cannot continue." Catch at boundaries, not at every call.
• Return (Result/error values) for expected, recoverable failures the caller must branch on — not-found, conflict, validation. A 404 is a result, not an exception.