error-handling

Handle errors so failures are visible and recoverable

Every error is a decision: recover, translate, or propagate. An empty catch makes that decision silently and wrongly. Design the error path with the happy path: typed errors with stable codes, context added on the way up with the cause preserved, and one place at the top that logs and decides what the caller sees.

Steps

1. Map the failure modes. For the code the ticket touches, list what can fail: invalid input, not found, conflict, permission, dependency down, timeout, and bugs. For each, decide who must know (caller, user, operator) and whether anything can be done. Call search_lore for the repo's error base class or result type and the API error envelope.
2. Use the repo's error shape. A typed error hierarchy or result type carrying a stable machine code (NOT_FOUND, CONFLICT) separate from the human message. Never throw strings. Use return values for expected outcomes where the language favours them (Go error, Rust Result) and exceptions for exceptional ones elsewhere.
3. Fail fast at boundaries. Validate input where it enters (the security-input-validation skill) and reject with the documented code before any side effect. Inside the boundary, trust your own types.
4. Wrap with context, keep the cause. Add what the caller needs (which record, which operation) and preserve the original:
   • JavaScript/TypeScript: new AppError(msg, { cause: err }); never throw "msg".
   • Python: raise AppError(msg) from err; add_note() for context.
   • Go: fmt.Errorf("load order %s: %w", id, err); test with errors.Is / errors.As; never compare error strings.
   • Rust: ? with thiserror types in libraries, anyhow::Context in binaries; no unwrap() on fallible runtime paths.
   • Java/Kotlin: pass the cause to the constructor; C#: throw; to rethrow, never throw ex; (it resets the stack trace).
5. Recover only where recovery is real. Retry only transient failures of idempotent operations, with backoff, jitter and a cap (the idempotency-and-retries skill). Fall back only when the degraded result is acceptable and is logged or counted. Otherwise propagate. An empty catch, except: pass, except Exception that continues, an ignored err, or .catch(() => {}) is a bug: handle it or delete it. Do not catch an error to hide a race or a bug (e.g. retrying on a temp-file collision instead of fixing it with the concurrency-and-async skill).
6. Leave no half-applied state. Fail before the first side effect, or make the sequence atomic (one transaction), or compensate explicitly. Release resources in finally / defer / using / with.
7. Report once, at the top. The outermost handler (request middleware, job runner, CLI main) logs once with code, context, cause chain and correlation id through the structured logger (the structured-logging-and-tracing skill); intermediate layers wrap, they do not log and rethrow. It maps typed errors to the external contract: for HTTP, the repo's envelope or RFC 9457 problem details (type, title, status, detail) with the right status (400/422 validation, 404, 409 conflict, 503 dependency unavailable, 500 only for bugs). Stack traces, SQL, file paths and secrets never reach a client. Install process-level handlers (unhandled rejection, uncaught exception, panic recovery at the goroutine or request boundary) that log and exit or fail the request, never continue in an unknown state.
8. Test the error paths as first-class cases, one test per AC exercising the AC's own behaviour: each failure mode asserts the error code or status, the body shape, that the cause is preserved (or logged), and that no partial write or side effect happened. Inject failures with fakes or fault hooks, not by editing production code.
9. Evidence with the record-evidence skill.