errorslisted

The point of an error is to make debugging cheap. If reading the log line doesn't tell you what happened, what was expected, and where to look — the error failed at its job. This skill covers how to design and throw errors that carry that information every time. Pairs with `logging` — errors get emitted through the global handler that adds request context, trace-id, and the full cause chain. The trace-id itself belongs to `logging`; this skill only carries it into the response. ## Example prompts - "Add error handling for the user-lookup route" - "Refactor these `throw new Error('X')` calls to something typed" - "What should the error shape look like for this API?" - "Review this handler for error discipline" ## Core principles 1. **Every error self-explains.** From the log line alone, a reader should know: *what* happened, *what was expected*, and *where* to look next. `Error("not found")` fails this test. `NotFoundError("user", { id })` passes. 2. **Codes over stack traces for categorization.** A stable string code (e.g. `USER_NOT_FOUND`, `TOKEN_EXPIRED`, `RATE_LIMITED`) is greppable, dashboard-friendly, and stable across refactors. Stack traces are for one-off debugging, codes are for aggregation. 3. **Distinguish expected from unexpected.** - **Expected** (validation, auth, not-found, conflict, rate-limit) — a normal outcome, log at WARN or INFO, return a clean response to the caller. - **Unexpected** (a null dereference, downstream 500, DB unreachable) — a b