Error Handling Strategies

Author: Htunn Thu Thu

Date: January 4, 2026

Tags: #SoftwareDesign #TypeScript #ErrorHandling #Reliability

Introduction

Good error handling is the difference between an application that crashes mysteriously and one that fails gracefully. Building distributed systems like my IoT monitoring platform taught me that errors aren't exceptional—they're normal, and we need to design for them.

This guide covers:

• Error Types - Understanding different error categories

• Error Handling Patterns - Try-catch, Result types, error boundaries

• Defensive Programming - Validation and safeguards

• Fault Tolerance - Retries, fallbacks, circuit breakers

• Error Reporting - Logging and monitoring

---

Understanding Error Types

Operational vs. Programming Errors

// Operational errors: Expected runtime issues
// - Network failures
// - Database connection lost
// - Invalid user input
// - File not found
// - API rate limits exceeded

// Programming errors: Bugs in code
// - TypeError: Cannot read property of undefined
// - ReferenceError: Variable not declared
// - Logic errors
// - Incorrect assumptions

Real Example from My Projects

// ✅ REAL: Error classification in my MCP server

class SecurityScanError extends Error {
  constructor(
    message: string,
    public readonly type: 'operational' | 'programming',
    public readonly recoverable: boolean,
    public readonly details?: any
  ) {
    super(message);
    this.name = 'SecurityScanError';
  }
}

class PortScanError extends SecurityScanError {
  constructor(
    message: string,
    public readonly host: string,
    public readonly port: number,
    details?: any
  ) {
    super(message, 'operational', true, details);
    this.name = 'PortScanError';
  }
}

class SSLCheckError extends SecurityScanError {
  constructor(
    message: string,
    public readonly host: string,
    details?: any
  ) {
    super(message, 'operational', true, details);
    this.name = 'SSLCheckError';
  }
}

class ConfigurationError extends SecurityScanError {
  constructor(message: string, details?: any) {
    super(message, 'programming', false, details);
    this.name = 'ConfigurationError';
  }
}

---

Error Handling Patterns

Traditional Try-Catch

// ❌ BAD: Swallowing errors

async function fetchData(url: string): Promise<Data> {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (error) {
    console.log('Error occurred'); // Silent failure!
    return null; // Hides the problem
  }
}

// ✅ GOOD: Proper error handling

async function fetchData(url: string): Promise<Data> {
  try {
    const response = await fetch(url);
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    return await response.json();
  } catch (error) {
    // Log with context
    console.error(`Failed to fetch data from ${url}:`, error);
    
    // Re-throw for caller to handle
    throw new FetchError(`Failed to fetch from ${url}`, { cause: error });
  }
}

// Caller can decide how to handle
try {
  const data = await fetchData('https://api.example.com/data');
  processData(data);
} catch (error) {
  if (error instanceof FetchError) {
    // Show user-friendly message
    showError('Unable to load data. Please try again.');
  } else {
    // Unexpected error - log and report
    reportError(error);
  }
}

Result Type Pattern

Instead of throwing, return success or failure:

// ✅ GOOD: Result type for explicit error handling

type Result<T, E = Error> =
  | { success: true; value: T }
  | { success: false; error: E };

async function scanPort(host: string, port: number): Promise<Result<ScanResult>> {
  try {
    const socket = new net.Socket();
    socket.setTimeout(2000);
    
    const result = await new Promise<boolean>((resolve) => {
      socket.on('connect', () => {
        socket.destroy();
        resolve(true);
      });
      
      socket.on('timeout', () => {
        socket.destroy();
        resolve(false);
      });
      
      socket.on('error', () => {
        socket.destroy();
        resolve(false);
      });
      
      socket.connect(port, host);
    });
    
    return {
      success: true,
      value: { port, open: result }
    };
  } catch (error) {
    return {
      success: false,
      error: new PortScanError(`Scan failed for ${host}:${port}`, host, port, error)
    };
  }
}

// Usage - explicit error checking
const result = await scanPort('example.com', 443);

if (result.success) {
  console.log('Port scan result:', result.value);
} else {
  console.error('Scan failed:', result.error.message);
  // Handle specific error types
  if (result.error instanceof PortScanError) {
    // Retry with different port
  }
}

Real Example: My IoT Platform Error Handling

// ✅ REAL: Comprehensive error handling in IoT platform

type SensorReadResult = Result<SensorData, SensorError>;

class SensorError extends Error {
  constructor(
    message: string,
    public readonly sensorId: string,
    public readonly errorCode: string,
    public readonly retryable: boolean
  ) {
    super(message);
    this.name = 'SensorError';
  }
}

class SensorReader {
  async read(sensorId: string): Promise<SensorReadResult> {
    try {
      // Validate sensor ID
      if (!this.isValidSensorId(sensorId)) {
        return {
          success: false,
          error: new SensorError(
            `Invalid sensor ID: ${sensorId}`,
            sensorId,
            'INVALID_SENSOR_ID',
            false
          )
        };
      }
      
      // Attempt to read
      const data = await this.readFromDevice(sensorId);
      
      // Validate data
      const validationResult = this.validateData(data);
      if (!validationResult.valid) {
        return {
          success: false,
          error: new SensorError(
            `Invalid sensor data: ${validationResult.errors.join(', ')}`,
            sensorId,
            'INVALID_DATA',
            true // Can retry - might be transient
          )
        };
      }
      
      return {
        success: true,
        value: data
      };
    } catch (error) {
      // Categorize the error
      if (error instanceof NetworkError) {
        return {
          success: false,
          error: new SensorError(
            `Network error reading sensor ${sensorId}`,
            sensorId,
            'NETWORK_ERROR',
            true // Retryable
          )
        };
      }
      
      if (error instanceof TimeoutError) {
        return {
          success: false,
          error: new SensorError(
            `Timeout reading sensor ${sensorId}`,
            sensorId,
            'TIMEOUT',
            true // Retryable
          )
        };
      }
      
      // Unexpected error
      return {
        success: false,
        error: new SensorError(
          `Unexpected error reading sensor ${sensorId}: ${error}`,
          sensorId,
          'UNKNOWN_ERROR',
          false // Don't retry unknown errors
        )
      };
    }
  }
  
  private isValidSensorId(sensorId: string): boolean {
    return /^sensor-\d{3}$/.test(sensorId);
  }
  
  private validateData(data: SensorData): { valid: boolean; errors: string[] } {
    const errors: string[] = [];
    
    if (data.temperature < -50 || data.temperature > 100) {
      errors.push('Temperature out of range');
    }
    
    if (data.humidity < 0 || data.humidity > 100) {
      errors.push('Humidity out of range');
    }
    
    return {
      valid: errors.length === 0,
      errors
    };
  }
  
  private async readFromDevice(sensorId: string): Promise<SensorData> {
    // Actual device communication
    return { temperature: 22, humidity: 45 };
  }
}

---

Defensive Programming

Input Validation

// ✅ GOOD: Comprehensive input validation

class InputValidator {
  static validatePortNumber(port: number): void {
    if (!Number.isInteger(port)) {
      throw new ValidationError('Port must be an integer');
    }
    
    if (port < 1 || port > 65535) {
      throw new ValidationError(`Port ${port} out of range (1-65535)`);
    }
  }
  
  static validateHostname(host: string): void {
    if (!host || typeof host !== 'string') {
      throw new ValidationError('Host must be a non-empty string');
    }
    
    if (host.length > 253) {
      throw new ValidationError('Hostname too long');
    }
    
    // Simple hostname validation
    const hostnameRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
    
    if (!hostnameRegex.test(host)) {
      throw new ValidationError(`Invalid hostname: ${host}`);
    }
  }
  
  static validateTimeout(timeout: number): void {
    if (!Number.isInteger(timeout) || timeout <= 0) {
      throw new ValidationError('Timeout must be a positive integer');
    }
    
    if (timeout > 60000) {
      throw new ValidationError('Timeout too large (max 60000ms)');
    }
  }
}

// Usage with validation
class PortScanner {
  async scan(host: string, port: number, timeout: number = 2000): Promise<ScanResult> {
    // Validate all inputs
    InputValidator.validateHostname(host);
    InputValidator.validatePortNumber(port);
    InputValidator.validateTimeout(timeout);
    
    // Now safe to proceed
    return this.performScan(host, port, timeout);
  }
  
  private async performScan(host: string, port: number, timeout: number): Promise<ScanResult> {
    // Implementation
  }
}

Null Safety

// ❌ BAD: Unsafe property access

function getUserEmail(user: User): string {
  return user.profile.email; // Can throw if profile is undefined!
}

// ✅ GOOD: Safe navigation

function getUserEmail(user: User | null | undefined): string | null {
  return user?.profile?.email ?? null;
}

// ✅ BETTER: With validation

function getUserEmail(user: User | null | undefined): Result<string> {
  if (!user) {
    return {
      success: false,
      error: new Error('User is null or undefined')
    };
  }
  
  if (!user.profile) {
    return {
      success: false,
      error: new Error('User profile is missing')
    };
  }
  
  if (!user.profile.email) {
    return {
      success: false,
      error: new Error('Email address is missing')
    };
  }
  
  return {
    success: true,
    value: user.profile.email
  };
}

Real Example: Defensive Database Operations

// ✅ REAL: Defensive programming in my chatbot database layer

class ConversationRepository {
  constructor(private db: Db) {
    if (!db) {
      throw new ConfigurationError('Database instance is required');
    }
  }
  
  async save(conversationId: string, messages: Message[]): Promise<void> {
    // Validate inputs
    if (!conversationId || typeof conversationId !== 'string') {
      throw new ValidationError('Conversation ID must be a non-empty string');
    }
    
    if (!Array.isArray(messages)) {
      throw new ValidationError('Messages must be an array');
    }
    
    // Validate each message
    for (const msg of messages) {
      if (!msg.role || !msg.content) {
        throw new ValidationError('Each message must have role and content');
      }
      
      if (!['user', 'assistant', 'system'].includes(msg.role)) {
        throw new ValidationError(`Invalid message role: ${msg.role}`);
      }
    }
    
    try {
      const collection = this.db.collection('conversations');
      
      await collection.updateOne(
        { id: conversationId },
        {
          $set: {
            messages,
            updatedAt: new Date()
          },
          $setOnInsert: {
            createdAt: new Date()
          }
        },
        { upsert: true }
      );
    } catch (error) {
      throw new DatabaseError(
        `Failed to save conversation ${conversationId}`,
        { cause: error }
      );
    }
  }
  
  async load(conversationId: string): Promise<Message[]> {
    if (!conversationId || typeof conversationId !== 'string') {
      throw new ValidationError('Conversation ID must be a non-empty string');
    }
    
    try {
      const collection = this.db.collection('conversations');
      const doc = await collection.findOne({ id: conversationId });
      
      // Safe return even if not found
      return doc?.messages ?? [];
    } catch (error) {
      throw new DatabaseError(
        `Failed to load conversation ${conversationId}`,
        { cause: error }
      );
    }
  }
}

---

Fault Tolerance

Retry Logic

// ✅ GOOD: Exponential backoff retry

interface RetryOptions {
  maxAttempts: number;
  initialDelayMs: number;
  maxDelayMs: number;
  backoffMultiplier: number;
}

async function withRetry<T>(
  operation: () => Promise<T>,
  options: RetryOptions,
  shouldRetry: (error: any) => boolean = () => true
): Promise<T> {
  let lastError: any;
  let delay = options.initialDelayMs;
  
  for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      
      // Don't retry if shouldn't or last attempt
      if (!shouldRetry(error) || attempt === options.maxAttempts) {
        break;
      }
      
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      
      // Wait with exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
      
      // Increase delay for next retry
      delay = Math.min(delay * options.backoffMultiplier, options.maxDelayMs);
    }
  }
  
  throw lastError;
}

// Usage
async function fetchWithRetry(url: string): Promise<Data> {
  return withRetry(
    () => fetch(url).then(r => r.json()),
    {
      maxAttempts: 3,
      initialDelayMs: 1000,
      maxDelayMs: 10000,
      backoffMultiplier: 2
    },
    (error) => {
      // Only retry on network errors, not 4xx errors
      return !(error instanceof HttpError && error.status < 500);
    }
  );
}

Circuit Breaker Pattern

// ✅ REAL: Circuit breaker in my IoT platform

enum CircuitState {
  CLOSED,   // Normal operation
  OPEN,     // Failing, reject requests
  HALF_OPEN // Testing if service recovered
}

class CircuitBreaker<T> {
  private state: CircuitState = CircuitState.CLOSED;
  private failureCount: number = 0;
  private lastFailureTime: number = 0;
  private successCount: number = 0;
  
  constructor(
    private options: {
      failureThreshold: number;
      resetTimeoutMs: number;
      halfOpenSuccessThreshold: number;
    }
  ) {}
  
  async execute(operation: () => Promise<T>): Promise<T> {
    if (this.state === CircuitState.OPEN) {
      // Check if we should try again
      if (Date.now() - this.lastFailureTime > this.options.resetTimeoutMs) {
        console.log('Circuit breaker: Moving to HALF_OPEN state');
        this.state = CircuitState.HALF_OPEN;
        this.successCount = 0;
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }
    
    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  private onSuccess(): void {
    this.failureCount = 0;
    
    if (this.state === CircuitState.HALF_OPEN) {
      this.successCount++;
      
      if (this.successCount >= this.options.halfOpenSuccessThreshold) {
        console.log('Circuit breaker: Moving to CLOSED state');
        this.state = CircuitState.CLOSED;
        this.successCount = 0;
      }
    }
  }
  
  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    if (this.failureCount >= this.options.failureThreshold) {
      console.log('Circuit breaker: Moving to OPEN state');
      this.state = CircuitState.OPEN;
    }
  }
  
  getState(): CircuitState {
    return this.state;
  }
  
  reset(): void {
    this.state = CircuitState.CLOSED;
    this.failureCount = 0;
    this.successCount = 0;
  }
}

// Usage - protect external API calls
class LLMService {
  private circuitBreaker = new CircuitBreaker({
    failureThreshold: 5,
    resetTimeoutMs: 60000,
    halfOpenSuccessThreshold: 2
  });
  
  async analyze(prompt: string): Promise<string> {
    try {
      return await this.circuitBreaker.execute(async () => {
        const response = await fetch('https://api.openai.com/v1/chat/completions', {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${API_KEY}` },
          body: JSON.stringify({ messages: [{ role: 'user', content: prompt }] })
        });
        
        if (!response.ok) {
          throw new Error(`API error: ${response.status}`);
        }
        
        const data = await response.json();
        return data.choices[0].message.content;
      });
    } catch (error) {
      // Circuit is open, use fallback
      console.log('Using fallback analysis');
      return this.fallbackAnalysis(prompt);
    }
  }
  
  private fallbackAnalysis(prompt: string): string {
    return 'Analysis temporarily unavailable. Please try again later.';
  }
}

Fallback Strategies

// ✅ REAL: Multi-level fallback in my agentic LLM project

class SmartSearchService {
  constructor(
    private primarySearch: SearchAPI,
    private secondarySearch: SearchAPI,
    private cache: Cache
  ) {}
  
  async search(query: string): Promise<SearchResult[]> {
    // Level 1: Try cache
    const cached = await this.tryCache(query);
    if (cached) {
      console.log('Cache hit');
      return cached;
    }
    
    // Level 2: Try primary search
    const primaryResult = await this.tryPrimarySearch(query);
    if (primaryResult.success) {
      await this.cache.set(query, primaryResult.value);
      return primaryResult.value;
    }
    
    console.log('Primary search failed:', primaryResult.error);
    
    // Level 3: Try secondary search
    const secondaryResult = await this.trySecondarySearch(query);
    if (secondaryResult.success) {
      await this.cache.set(query, secondaryResult.value);
      return secondaryResult.value;
    }
    
    console.log('Secondary search failed:', secondaryResult.error);
    
    // Level 4: Return empty results with error
    return [];
  }
  
  private async tryCache(query: string): Promise<SearchResult[] | null> {
    try {
      return await this.cache.get(query);
    } catch (error) {
      console.log('Cache error:', error);
      return null;
    }
  }
  
  private async tryPrimarySearch(query: string): Promise<Result<SearchResult[]>> {
    try {
      const results = await this.primarySearch.search(query);
      return { success: true, value: results };
    } catch (error) {
      return {
        success: false,
        error: new Error(`Primary search failed: ${error}`)
      };
    }
  }
  
  private async trySecondarySearch(query: string): Promise<Result<SearchResult[]>> {
    try {
      const results = await this.secondarySearch.search(query);
      return { success: true, value: results };
    } catch (error) {
      return {
        success: false,
        error: new Error(`Secondary search failed: ${error}`)
      };
    }
  }
}

---

Error Reporting and Logging

Structured Logging

// ✅ GOOD: Structured error logging

interface LogContext {
  service: string;
  operation: string;
  userId?: string;
  tenantId?: string;
  correlationId?: string;
  [key: string]: any;
}

class Logger {
  error(message: string, error: Error, context: LogContext): void {
    const logEntry = {
      timestamp: new Date().toISOString(),
      level: 'ERROR',
      message,
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack,
        ...(error instanceof AppError ? { code: error.code, details: error.details } : {})
      },
      context
    };
    
    console.error(JSON.stringify(logEntry));
    
    // Send to monitoring service
    this.sendToMonitoring(logEntry);
  }
  
  warn(message: string, context: LogContext): void {
    console.warn(JSON.stringify({
      timestamp: new Date().toISOString(),
      level: 'WARN',
      message,
      context
    }));
  }
  
  info(message: string, context: LogContext): void {
    console.info(JSON.stringify({
      timestamp: new Date().toISOString(),
      level: 'INFO',
      message,
      context
    }));
  }
  
  private sendToMonitoring(entry: any): void {
    // Send to Application Insights, Datadog, etc.
  }
}

// Usage
const logger = new Logger();

try {
  await scanPort('example.com', 443);
} catch (error) {
  logger.error(
    'Port scan failed',
    error as Error,
    {
      service: 'security-scanner',
      operation: 'port-scan',
      host: 'example.com',
      port: 443,
      correlationId: requestId
    }
  );
}

Error Monitoring

// ✅ REAL: Error reporting in my production apps

class ErrorReporter {
  static report(error: Error, context: Record<string, any> = {}): void {
    // Log locally
    console.error('Error occurred:', {
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack
      },
      context,
      timestamp: new Date().toISOString()
    });
    
    // Don't report programming errors in production
    if (error instanceof AppError && !error.shouldReport) {
      return;
    }
    
    // Send to error tracking service
    this.sendToSentry(error, context);
  }
  
  private static sendToSentry(error: Error, context: Record<string, any>): void {
    // Integration with Sentry, Rollbar, etc.
    try {
      // Sentry.captureException(error, { extra: context });
    } catch (reportError) {
      console.error('Failed to report error:', reportError);
    }
  }
}

// Global error handler
process.on('unhandledRejection', (error: Error) => {
  ErrorReporter.report(error, {
    type: 'unhandledRejection',
    fatal: true
  });
  
  // Give time to send error report before exiting
  setTimeout(() => {
    process.exit(1);
  }, 1000);
});

process.on('uncaughtException', (error: Error) => {
  ErrorReporter.report(error, {
    type: 'uncaughtException',
    fatal: true
  });
  
  setTimeout(() => {
    process.exit(1);
  }, 1000);
});

---

Best Practices

1. Fail Fast

Validate inputs early and throw errors immediately for programming errors.

2. Be Specific

Use custom error types with context rather than generic Error.

3. Document Error Conditions

Specify what errors a function can throw in JSDoc.

/**
 * Scans a port on the specified host.
 * 
 * @throws {ValidationError} If host or port is invalid
 * @throws {PortScanError} If the scan operation fails
 * @throws {TimeoutError} If the scan times out
 */
async function scanPort(host: string, port: number): Promise<ScanResult> {
  // ...
}

4. Don't Swallow Errors

Always log or re-throw errors; never silently catch and ignore.

5. Provide Context

Include relevant information in error messages (what failed, why, what was attempted).

6. Use Type Guards

Check error types before handling:

if (error instanceof NetworkError) {
  // Retry
} else if (error instanceof ValidationError) {
  // Don't retry
}

---

Conclusion

Robust error handling requires:

• Clear Error Types: Distinguish operational from programming errors

• Explicit Handling: Use Result types or proper try-catch

• Defensive Programming: Validate inputs and check nulls

• Fault Tolerance: Implement retries, circuit breakers, fallbacks

• Proper Logging: Structured logging with context

I apply these strategies across all my TypeScript projects for production-ready reliability.

What's Next?

• Component Design → - Review modular architecture

• SOLID Principles → - Core design principles

• Design Patterns → - Pattern implementations

References

• My IoT Platform - Fault tolerance in distributed systems

• Node.js Error Handling Best Practices

---

Previous: ← Component Design | Up: Software Design 101 ↑