error-handlinglisted

## 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](${CLAUDE_PLUGIN_ROOT}/skills/03-design/architecture/references/error-resilience.md) 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,