error-handling

Error Handling Patterns

Consistent, robust error handling patterns for production applications.

When to Activate

• Designing error types or exception hierarchies for a new module or service
• Adding retry logic or circuit breakers for unreliable external dependencies
• Reviewing API endpoints for missing error handling
• Implementing user-facing error messages and feedback
• Debugging cascading failures or silent error swallowing

Core Principles

1. Fail fast and loudly — surface errors at the boundary where they occur; don't bury them
2. Typed errors over string messages — errors are first-class values with structure
3. User messages ≠ developer messages — show friendly text to users, log full context server-side
4. Never swallow errors silently — every catch block must either handle, re-throw, or log
5. Errors are part of your API contract — document every error code a client may receive

TypeScript / JavaScript

Typed Error Classes

// Define an error hierarchy for your domain
export class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
    public readonly details?: unknown,
  ) {
    super(message)
    this.name = this.constructor.name
    // Maintain correct prototype chain in transpiled ES5 JavaScript.
    // Required for `instanceof` checks (e.g., `error instanceof NotFoundError`)
    // to work correctly when extending the built-in Error class.
    Object.setPrototypeOf(this, new.target.prototype)
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
  }
}

export class ValidationError extends AppError {
  constructor(message: string, details: { field: string; message: string }[]) {
    super(message, 'VALIDATION_ERROR', 422, details)
  }
}

export class UnauthorizedError extends AppError {
  constructor(reason = 'Authentication required') {
    super(reason, 'UNAUTHORIZED', 401)
  }
}

export class RateLimitError extends AppError {
  constructor(public readonly retryAfterMs: number) {
    super('Rate limit exceeded', 'RATE_LIMITED', 429)
  }
}