principle-error-handling

Error Handling

Errors are part of the contract. Handling them is not defensive programming — it is the design.

Errors as Values vs Exceptions

Use the language's native error style; don't fight it.

• Go error values, Rust Result<T, E>, TypeScript typed unions: errors are explicit return paths, visible in signatures, handled by callers.
• Exceptions (Java, Python, C#) work best for truly unexpected conditions — programmer errors, not business failures.
• Reserve panic / throw / unchecked exceptions for unrecoverable programmer errors. Expected failures (network timeout, not found) must be value-level errors.

Classify Before Handling

Not all errors deserve the same response.

• Transient — network blip, timeout, lock contention: retry with backoff (fail soft — degrade gracefully while recovering).
• Permanent — bad input, not found, permission denied: fail fast — surface immediately to the caller, never retry.
• Programmer — nil deref, index out of bounds, invariant violated: panic/crash, fix the code.
• Misclassifying a permanent error as transient wastes retry budget and delays the caller.

Wrap, Don't Swallow

At each layer boundary, add context to the error and preserve the original cause for downstream inspection.

• Go: fmt.Errorf("loading user config: %w", err) — %w preserves errors.Is / errors.As traversal.
• Rust: anyhow::Context / .with_context(|| ...) — attach human-readable context without losing the source.
• TypeScript: native Error supports a cause option — new Error("fetch failed", { cause: err }).
• Never discard the original error (return errors.New("failed") with no wrapping). The original context is lost forever.

Sentinel vs Typed vs Coded Errors

Three models; choose based on callsite needs.

Sentinel errors (Go io.EOF, Rust ErrorKind::NotFound)

• Use when: callers need to branch on a single known condition without importing a type.
• Costs: error set is open; callers do string-equal or errors.Is identity checks; hard to carry payload.
• Don't use when: the error needs structured data (retry-after, field name, status code).