error-handling

Error Handling Rules

Error Class Hierarchy

// Base error class
export class AppError extends Error {
  constructor(
    public readonly code: string,
    public readonly message: string,
    public readonly statusCode: number,
    public readonly details?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

// Specific error types
export class ValidationError extends AppError {
  constructor(message: string, details?: Record<string, unknown>) {
    super('VALIDATION_ERROR', message, 400, details);
  }
}

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

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

export class ForbiddenError extends AppError {
  constructor(message = 'Insufficient permissions') {
    super('FORBIDDEN', message, 403);
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super('CONFLICT', message, 409);
  }
}

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid order data",
    "details": {
      "fields": [
        { "field": "quantity", "message": "Must be a positive integer" }
      ]
    }
  },
  "meta": {
    "correlationId": "abc-123",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

Rules

• ALWAYS use typed error classes — never throw raw strings or generic Errors
• NEVER expose stack traces or internal details to API consumers
• ALWAYS log the full error server-side (with stack trace, context)
• ALWAYS include correlationId in error responses
• Use centralized error handling middleware — don't try/catch in every handler
• Map all errors to appropriate HTTP status codes
• Return consistent error response shape across all endpoints