Designing Scalable Error Handling Systems in TypeScript for Distributed Architectures

Handling errors effectively in distributed systems can be challenging. Applications composed of multiple services often involve asynchronous processes, network delays, and diverse environments. Designing an error handling approach that scales well and provides clear information is essential for maintaining reliability and ease of debugging. In this article, we'll explore creating a scalable error handling system using TypeScript, with practical examples and best practices for distributed architectures.

### Why Focus on Error Handling in Distributed Systems?

Distributed systems involve multiple services communicating over the network. Errors can happen at different points: the client, network requests, individual services, or downstream dependencies. A scalable error system helps you centralize error definitions, standardize logs, and enable easier tracing across services.

### Step 1: Define a Base Error Class

To handle errors systematically, start by defining a base error class in TypeScript. This class should extend the built-in `Error` and include additional properties such as error codes, metadata, or service context.

class BaseError extends Error {
  public readonly code: string;
  public readonly metadata?: Record<string, any>;

  constructor(message: string, code: string, metadata?: Record<string, any>) {
    super(message);
    this.code = code;
    this.metadata = metadata;
    // Set the prototype explicitly to maintain instanceof checks
    Object.setPrototypeOf(this, new.target.prototype);
  }
}

This `BaseError` class provides a foundation. The `code` property helps identify the error type programmatically, and `metadata` can hold additional context.

### Step 2: Create Specific Error Subclasses

Define specific error classes for common scenarios. This helps with granularity when handling different failure points.

class NetworkError extends BaseError {
  constructor(message: string, metadata?: Record<string, any>) {
    super(message, 'NETWORK_ERROR', metadata);
  }
}

class ValidationError extends BaseError {
  constructor(message: string, metadata?: Record<string, any>) {
    super(message, 'VALIDATION_ERROR', metadata);
  }
}

class DatabaseError extends BaseError {
  constructor(message: string, metadata?: Record<string, any>) {
    super(message, 'DATABASE_ERROR', metadata);
  }
}

These subclasses include meaningful error codes and can carry specific metadata related to the error context.

### Step 3: Centralize Error Handling Middleware or Functions

In distributed services, use error handling middleware or a centralized function to catch thrown errors, log them with appropriate context, and format responses. For example, in an Express.js microservice:

import { Request, Response, NextFunction } from 'express';

function errorHandler(err: BaseError, req: Request, res: Response, next: NextFunction) {
  console.error(`[${err.code}] - ${err.message}`, err.metadata);

  const statusMap: Record<string, number> = {
    VALIDATION_ERROR: 400,
    NETWORK_ERROR: 503,
    DATABASE_ERROR: 500,
  };

  const status = statusMap[err.code] || 500;

  res.status(status).json({
    error: {
      code: err.code,
      message: err.message,
      metadata: err.metadata,
    },
  });
}

export default errorHandler;

This centralized error middleware logs the error with details and sends a structured JSON response, making debugging and client-side handling easier.

### Step 4: Propagate and Handle Errors Across Services

When services communicate (e.g., via HTTP or message queues), design your error responses to include error codes and context fields. This allows clients or other services to react appropriately.

interface ErrorResponse {
  code: string;
  message: string;
  metadata?: Record<string, any>;
}

// Example service response handler
async function fetchData(): Promise<void> {
  try {
    const response = await fetch('http://otherservice/api');
    if (!response.ok) {
      const errorBody: ErrorResponse = await response.json();
      throw new BaseError(errorBody.message, errorBody.code, errorBody.metadata);
    }
    // process data
  } catch (err) {
    if (err instanceof BaseError) {
      // Handle known errors
      console.log(`Handled error code: ${err.code}`);
    } else {
      // Handle unexpected errors
      console.error('Unexpected error', err);
    }
  }
}

### Step 5: Use Error Logging and Monitoring Tools

Integrate logging frameworks (e.g., Winston, Pino) and monitoring tools (e.g., Sentry, Datadog) to capture errors in production. Structured error classes make it easier to enrich logs with meaningful fields.

### Final Thoughts

Designing scalable error handling in TypeScript for distributed systems requires thoughtful error classification, propagation, and centralized handling. This approach promotes maintainability, better debugging, and smoother client experiences. Using typed error classes aligned with service boundaries enhances clarity across your architecture.

Start simple, and gradually add error specifics and monitoring to keep your error handling robust as your system grows.