error-handling

name	error-handling
description	Use when: design error handling so failures are explicit, recoverable, and never silently swallowed.

Goal: failures that are visible, contextual, and handled deliberately.

Use for:

• deciding how functions signal and propagate failure
• reviewing try/catch, error types, and recovery
• fixing swallowed errors and vague messages

Workflow:

1. Distinguish expected failures from programmer bugs.
2. Model expected errors explicitly (results or typed exceptions).
3. Handle errors where you can act; otherwise propagate with context.
4. Add context as errors cross boundaries, without losing the cause.
5. Fail fast on invariant violations; do not limp on.
6. Surface actionable messages; log details once, near the source.

Patterns:

• typed errors or result types over generic throws
• wrap-and-rethrow to add context, preserving the cause
• retry with backoff for transient failures only
• a single place that maps errors to user-facing responses

Rules:

• never swallow an error silently
• do not catch broadly just to continue; handle or rethrow
• include context, never the bare message
• distinguish retryable failures from permanent ones