error-handling-patterns

Error Handling Patterns

Core Principles

1. Errors are data, not strings — use structured error types with codes, messages, and context
2. Handle at boundaries — catch at architectural boundaries (API, service, data layer), not everywhere
3. User-facing errors are safe — never expose stack traces, internal paths, or implementation details
4. Errors are loggable — every error carries enough context to debug without reproducing
5. Recovery is explicit — every catch block states its recovery strategy

Structured Error Pattern

class AppError extends Error {
  constructor(
    public code: string,
    message: string,
    public statusCode: number = 500,
    public context?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'AppError';
  }
}
throw new AppError('USER_NOT_FOUND', 'User does not exist', 404, { userId });

Boundary Error Handling

• API Layer: Catch all, map to HTTP status, return safe JSON, log full error with correlation ID
• Service Layer: Catch specific expected errors, add context, re-throw as AppError
• Data Layer: Catch DB-specific errors, translate to domain errors (duplicate key → CONFLICT)

Recovery Strategies

Every catch block must implement one of:

1. Retry — transient failures (network, rate limits). Exponential backoff.
2. Fallback — degrade gracefully (cache, default value)
3. Propagate — re-throw with added context for the next boundary
4. Fail fast — unrecoverable. Log, clean up, terminate the operation.

Anti-Patterns

• catch (e) {} — silent swallowing. NEVER.
• catch (e) { console.log(e) } — logged but not handled. What's the recovery?
• Catching too broadly at the wrong layer
• Wrapping every function call in try/catch