Error Handling

Design robust error handling strategies for applications. Covers error classification hierarchies, retry policies with backoff, circuit breaker patterns, graceful degradation, structured error reporting, and user-facing error messages.

Workflow

Step 1: Assess the Current State

Understand how errors are currently handled:

• Read the codebase: Search for try/catch, catch, .catch(, rescue, except, recover patterns.
• Check for swallowed errors: Look for empty catch blocks or catch blocks that only log.
• Review error responses: Check API error response formats for consistency.
• Check logging: Look for structured logging setup (winston, pino, loguru, slog).
• Check monitoring: Look for error tracking integration (Sentry, Datadog, Bugsnag).

Common anti-patterns to identify:

• Catching Exception or Error base class everywhere (too broad).
• Swallowing errors silently (catch (e) {}).
• Returning null on failure instead of throwing (hides errors).
• Inconsistent error response formats across API endpoints.
• Missing error boundaries in frontend (entire app crashes on one component error).
• No retry logic for transient failures (network timeouts, rate limits).
• Logging sensitive data in error messages (passwords, tokens, PII).

Step 2: Design Error Hierarchy

Create a structured error class hierarchy for the application:

TypeScript/JavaScript:

// Base application error
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
    public readonly isOperational: boolean = true,
    public readonly context?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

// Specific error types
class ValidationError extends AppError {
  constructor(message: string, public readonly fields: FieldError[]) {
    super(message, 'VALIDATION_ERROR', 422);
  }
}

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

class AuthenticationError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 'UNAUTHENTICATED', 401);
  }
}

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

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

class ExternalServiceError extends AppError {
  constructor(service: string, cause?: Error) {
    super(`External service failure: ${service}`, 'EXTERNAL_SERVICE_ERROR', 502);
    if (cause) this.cause = cause;
  }
}

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

Python:

class AppError(Exception):
    def __init__(self, message: str, code: str, status_code: int = 500,
                 is_operational: bool = True, context: dict | None = None):
        super().__init__(message)
        self.code = code
        self.status_code = status_code
        self.is_operational = is_operational
        self.context = context or {}

class ValidationError(AppError):
    def __init__(self, message: str, fields: list[dict]):
        super().__init__(message, "VALIDATION_ERROR", 422)
        self.fields = fields

class NotFoundError(AppError):
    def __init__(self, resource: str, id: str):
        super().__init__(f"{resource} with id {id} not found", "NOT_FOUND", 404)

class ExternalServiceError(AppError):
    def __init__(self, service: str, cause: Exception | None = None):
        super().__init__(f"External service failure: {service}",
                        "EXTERNAL_SERVICE_ERROR", 502)
        self.__cause__ = cause

Operational vs. Programmer Errors:

• Operational errors (expected): Invalid input, network timeout, resource not found. Handle gracefully.
• Programmer errors (bugs): Null dereference, type error, assertion failure. Let them crash and fix the code.

Step 3: Retry Policies

Design retry logic for transient failures:

Exponential backoff with jitter:

async function withRetry<T>(
  fn: () => Promise<T>,
  options: {
    maxRetries?: number;
    baseDelayMs?: number;
    maxDelayMs?: number;
    retryOn?: (error: Error) => boolean;
  } = {}
): Promise<T> {
  const {
    maxRetries = 3,
    baseDelayMs = 200,
    maxDelayMs = 10000,
    retryOn = isTransient,
  } = options;

  let lastError: Error;
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      if (attempt === maxRetries || !retryOn(lastError)) {
        throw lastError;
      }
      const delay = Math.min(
        baseDelayMs * Math.pow(2, attempt) + Math.random() * baseDelayMs,
        maxDelayMs
      );
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw lastError!;
}

function isTransient(error: Error): boolean {
  if (error instanceof RateLimitError) return true;
  if (error instanceof ExternalServiceError) return true;
  if ('statusCode' in error) {
    const code = (error as any).statusCode;
    return code === 429 || code === 502 || code === 503 || code === 504;
  }
  return false;
}

What to retry:

• Network timeouts and connection errors
• HTTP 429 (rate limited), 502, 503, 504 responses
• Database connection failures
• Message queue publish failures

What NOT to retry:

• HTTP 400, 401, 403, 404, 422 (client errors, retrying will not help)
• Validation errors
• Business logic errors
• Authentication failures

Step 4: Circuit Breaker Pattern

Prevent cascading failures when an external service is down:

class CircuitBreaker {
  private state: 'closed' | 'open' | 'half-open' = 'closed';
  private failureCount = 0;
  private lastFailureTime = 0;
  private successCount = 0;

  constructor(
    private readonly options: {
      failureThreshold: number;    // failures before opening
      resetTimeoutMs: number;      // time before trying again
      successThreshold: number;    // successes before closing
    }
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailureTime > this.options.resetTimeoutMs) {
        this.state = 'half-open';
        this.successCount = 0;
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    if (this.state === 'half-open') {
      this.successCount++;
      if (this.successCount >= this.options.successThreshold) {
        this.state = 'closed';
        this.failureCount = 0;
      }
    } else {
      this.failureCount = 0;
    }
  }

  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    if (this.failureCount >= this.options.failureThreshold) {
      this.state = 'open';
    }
  }
}

// Usage
const paymentCircuit = new CircuitBreaker({
  failureThreshold: 5,
  resetTimeoutMs: 30000,
  successThreshold: 3,
});

const result = await paymentCircuit.execute(() => paymentService.charge(order));

Step 5: Graceful Degradation

Design fallback behaviors when dependencies fail:

// Example: feature with fallback
async function getRecommendations(userId: string): Promise<Product[]> {
  try {
    // Primary: ML recommendation service
    return await recommendationService.getPersonalized(userId);
  } catch (error) {
    logger.warn('Recommendation service unavailable, falling back', { error });

    try {
      // Fallback 1: cached recommendations
      return await cache.get(`recommendations:${userId}`);
    } catch {
      // Fallback 2: popular items (always available)
      return await getPopularProducts();
    }
  }
}

Degradation levels:

1. Full functionality: All services healthy, all features available.
2. Reduced functionality: Non-critical service down, feature disabled with notification.
3. Read-only mode: Write services down, reads still work from cache or replica.
4. Maintenance mode: Critical failure, show status page, queue requests for replay.

Step 6: Error Reporting and Observability

Structured error logging:

// Global error handler for Express
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  const isOperational = err instanceof AppError && err.isOperational;

  // Log with structured context
  logger.error({
    error: {
      name: err.name,
      message: err.message,
      code: err instanceof AppError ? err.code : 'INTERNAL_ERROR',
      stack: err.stack,
    },
    request: {
      method: req.method,
      path: req.path,
      userId: req.user?.id,
      requestId: req.headers['x-request-id'],
    },
    operational: isOperational,
  });

  // Report to error tracking
  if (!isOperational) {
    errorTracker.captureException(err, {
      user: req.user,
      request: { method: req.method, url: req.url },
    });
  }

  // Send response
  const statusCode = err instanceof AppError ? err.statusCode : 500;
  res.status(statusCode).json({
    error: {
      code: err instanceof AppError ? err.code : 'INTERNAL_ERROR',
      message: isOperational ? err.message : 'An unexpected error occurred',
    },
  });
});

Never expose internal details to users:

• Production error responses should not include stack traces.
• Use error codes that the client can map to user-friendly messages.
• Log the full error internally for debugging.

Output Format

## Error Handling Design

### Error Hierarchy
<class diagram or code for error classes>

### Error Response Format
```json
<standard error response shape>

Retry Policy

Circuit Breakers

Degradation Strategy

Error Reporting

• Logging: <structured logging setup>
• Tracking: <error tracking integration>
• Alerting: <alert rules for error rates>

Implementation Checklist

• Error hierarchy implemented
• Global error handler configured
• Retry logic for external calls
• Circuit breakers for critical dependencies
• Structured logging with request context
• Error tracking integration
• User-facing error messages reviewed

## Examples

**User**: "Design error handling for our Node.js API"
**Action**: Read the project structure, design an error class hierarchy, create a global error handler, add retry logic for external service calls, configure structured logging.

**User**: "We keep getting timeout errors from the payment service"
**Action**: Implement a circuit breaker around the payment service, add retry with exponential backoff for transient failures, design a fallback (queue for later processing), set up alerting.

**User**: "Our API returns inconsistent error formats"
**Action**: Audit all error responses, design a standard error format (RFC 7807), create a global error handler that normalizes all errors, update endpoints to throw typed errors.

**User**: "How should I handle errors in my React app?"
**Action**: Implement Error Boundaries for component-level recovery, design a global error handler for unhandled promise rejections, create user-friendly error UI components, set up client-side error reporting.

## Best Practices

- Fail fast for programmer errors. Do not try to recover from null dereferences or type errors; let them crash and fix the bug.
- Handle operational errors gracefully. Network failures, invalid input, and missing resources are expected in production; the application should handle them without crashing.
- Use typed errors, not string messages, as the basis for error handling decisions. Checking `error.code === 'NOT_FOUND'` is reliable; checking `error.message.includes('not found')` is fragile.
- Always include context in error logs: request ID, user ID, operation name, and relevant parameters. An error message without context is useless for debugging.
- Never log sensitive data (passwords, tokens, PII) in error messages or context.
- Design retry policies per dependency, not globally. A payment service and a cache have very different retry needs.
- Set timeouts on every external call. A missing timeout is a potential resource leak waiting to happen.
- Use circuit breakers for external dependencies to prevent cascading failures. A dead service should not bring down your entire application.
- Test error paths as thoroughly as happy paths. Most production outages happen in error handling code that was never tested.
- Distinguish between errors the user can fix (validation, auth) and errors they cannot (internal failures). The error message and HTTP status code should reflect this.