Error Handling Patterns

Build bulletproof apps with robust error handling across all languages

✨ The solution you've been looking for

Verified
Tested and verified by our team
25450 Stars

Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability.

error-handling resilience exceptions result-types circuit-breaker retry-patterns fault-tolerance debugging
Repository

See It In Action

Interactive preview & real-world examples

Live Demo
Skill Demo Animation

AI Conversation Simulator

See how users interact with this skill

User Prompt

Help me implement comprehensive error handling for my Node.js API that handles validation errors, database failures, and external service timeouts gracefully

Skill Processing

Analyzing request...

Agent Response

Complete error handling implementation with custom error classes, proper HTTP status codes, logging, and graceful degradation patterns

Quick Start (3 Steps)

Get up and running in minutes

1

Install

claude-code skill install error-handling-patterns

claude-code skill install error-handling-patterns
2

Config

3

First Trigger

@error-handling-patterns help

Commands

CommandDescriptionRequired Args
@error-handling-patterns implementing-graceful-api-error-handlingDesign error handling for a REST API that provides meaningful responses and prevents cascading failuresNone
@error-handling-patterns building-fault-tolerant-distributed-systemsImplement circuit breakers, retry logic, and failure recovery for microservices architectureNone
@error-handling-patterns debugging-production-errorsAnalyze error patterns and implement better error tracking and debugging capabilitiesNone

Typical Use Cases

Implementing Graceful API Error Handling

Design error handling for a REST API that provides meaningful responses and prevents cascading failures

Building Fault-Tolerant Distributed Systems

Implement circuit breakers, retry logic, and failure recovery for microservices architecture

Debugging Production Errors

Analyze error patterns and implement better error tracking and debugging capabilities

Overview

Error Handling Patterns

Build resilient applications with robust error handling strategies that gracefully handle failures and provide excellent debugging experiences.

When to Use This Skill

  • Implementing error handling in new features
  • Designing error-resilient APIs
  • Debugging production issues
  • Improving application reliability
  • Creating better error messages for users and developers
  • Implementing retry and circuit breaker patterns
  • Handling async/concurrent errors
  • Building fault-tolerant distributed systems

Core Concepts

1. Error Handling Philosophies

Exceptions vs Result Types:

  • Exceptions: Traditional try-catch, disrupts control flow
  • Result Types: Explicit success/failure, functional approach
  • Error Codes: C-style, requires discipline
  • Option/Maybe Types: For nullable values

When to Use Each:

  • Exceptions: Unexpected errors, exceptional conditions
  • Result Types: Expected errors, validation failures
  • Panics/Crashes: Unrecoverable errors, programming bugs

2. Error Categories

Recoverable Errors:

  • Network timeouts
  • Missing files
  • Invalid user input
  • API rate limits

Unrecoverable Errors:

  • Out of memory
  • Stack overflow
  • Programming bugs (null pointer, etc.)

Language-Specific Patterns

Python Error Handling

Custom Exception Hierarchy:

 1class ApplicationError(Exception):
 2    """Base exception for all application errors."""
 3    def __init__(self, message: str, code: str = None, details: dict = None):
 4        super().__init__(message)
 5        self.code = code
 6        self.details = details or {}
 7        self.timestamp = datetime.utcnow()
 8
 9class ValidationError(ApplicationError):
10    """Raised when validation fails."""
11    pass
12
13class NotFoundError(ApplicationError):
14    """Raised when resource not found."""
15    pass
16
17class ExternalServiceError(ApplicationError):
18    """Raised when external service fails."""
19    def __init__(self, message: str, service: str, **kwargs):
20        super().__init__(message, **kwargs)
21        self.service = service
22
23# Usage
24def get_user(user_id: str) -> User:
25    user = db.query(User).filter_by(id=user_id).first()
26    if not user:
27        raise NotFoundError(
28            f"User not found",
29            code="USER_NOT_FOUND",
30            details={"user_id": user_id}
31        )
32    return user

Context Managers for Cleanup:

 1from contextlib import contextmanager
 2
 3@contextmanager
 4def database_transaction(session):
 5    """Ensure transaction is committed or rolled back."""
 6    try:
 7        yield session
 8        session.commit()
 9    except Exception as e:
10        session.rollback()
11        raise
12    finally:
13        session.close()
14
15# Usage
16with database_transaction(db.session) as session:
17    user = User(name="Alice")
18    session.add(user)
19    # Automatic commit or rollback

Retry with Exponential Backoff:

 1import time
 2from functools import wraps
 3from typing import TypeVar, Callable
 4
 5T = TypeVar('T')
 6
 7def retry(
 8    max_attempts: int = 3,
 9    backoff_factor: float = 2.0,
10    exceptions: tuple = (Exception,)
11):
12    """Retry decorator with exponential backoff."""
13    def decorator(func: Callable[..., T]) -> Callable[..., T]:
14        @wraps(func)
15        def wrapper(*args, **kwargs) -> T:
16            last_exception = None
17            for attempt in range(max_attempts):
18                try:
19                    return func(*args, **kwargs)
20                except exceptions as e:
21                    last_exception = e
22                    if attempt < max_attempts - 1:
23                        sleep_time = backoff_factor ** attempt
24                        time.sleep(sleep_time)
25                        continue
26                    raise
27            raise last_exception
28        return wrapper
29    return decorator
30
31# Usage
32@retry(max_attempts=3, exceptions=(NetworkError,))
33def fetch_data(url: str) -> dict:
34    response = requests.get(url, timeout=5)
35    response.raise_for_status()
36    return response.json()

TypeScript/JavaScript Error Handling

Custom Error Classes:

 1// Custom error classes
 2class ApplicationError extends Error {
 3  constructor(
 4    message: string,
 5    public code: string,
 6    public statusCode: number = 500,
 7    public details?: Record<string, any>,
 8  ) {
 9    super(message);
10    this.name = this.constructor.name;
11    Error.captureStackTrace(this, this.constructor);
12  }
13}
14
15class ValidationError extends ApplicationError {
16  constructor(message: string, details?: Record<string, any>) {
17    super(message, "VALIDATION_ERROR", 400, details);
18  }
19}
20
21class NotFoundError extends ApplicationError {
22  constructor(resource: string, id: string) {
23    super(`${resource} not found`, "NOT_FOUND", 404, { resource, id });
24  }
25}
26
27// Usage
28function getUser(id: string): User {
29  const user = users.find((u) => u.id === id);
30  if (!user) {
31    throw new NotFoundError("User", id);
32  }
33  return user;
34}

Result Type Pattern:

 1// Result type for explicit error handling
 2type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
 3
 4// Helper functions
 5function Ok<T>(value: T): Result<T, never> {
 6  return { ok: true, value };
 7}
 8
 9function Err<E>(error: E): Result<never, E> {
10  return { ok: false, error };
11}
12
13// Usage
14function parseJSON<T>(json: string): Result<T, SyntaxError> {
15  try {
16    const value = JSON.parse(json) as T;
17    return Ok(value);
18  } catch (error) {
19    return Err(error as SyntaxError);
20  }
21}
22
23// Consuming Result
24const result = parseJSON<User>(userJson);
25if (result.ok) {
26  console.log(result.value.name);
27} else {
28  console.error("Parse failed:", result.error.message);
29}
30
31// Chaining Results
32function chain<T, U, E>(
33  result: Result<T, E>,
34  fn: (value: T) => Result<U, E>,
35): Result<U, E> {
36  return result.ok ? fn(result.value) : result;
37}

Async Error Handling:

 1// Async/await with proper error handling
 2async function fetchUserOrders(userId: string): Promise<Order[]> {
 3  try {
 4    const user = await getUser(userId);
 5    const orders = await getOrders(user.id);
 6    return orders;
 7  } catch (error) {
 8    if (error instanceof NotFoundError) {
 9      return []; // Return empty array for not found
10    }
11    if (error instanceof NetworkError) {
12      // Retry logic
13      return retryFetchOrders(userId);
14    }
15    // Re-throw unexpected errors
16    throw error;
17  }
18}
19
20// Promise error handling
21function fetchData(url: string): Promise<Data> {
22  return fetch(url)
23    .then((response) => {
24      if (!response.ok) {
25        throw new NetworkError(`HTTP ${response.status}`);
26      }
27      return response.json();
28    })
29    .catch((error) => {
30      console.error("Fetch failed:", error);
31      throw error;
32    });
33}

Rust Error Handling

Result and Option Types:

 1use std::fs::File;
 2use std::io::{self, Read};
 3
 4// Result type for operations that can fail
 5fn read_file(path: &str) -> Result<String, io::Error> {
 6    let mut file = File::open(path)?;  // ? operator propagates errors
 7    let mut contents = String::new();
 8    file.read_to_string(&mut contents)?;
 9    Ok(contents)
10}
11
12// Custom error types
13#[derive(Debug)]
14enum AppError {
15    Io(io::Error),
16    Parse(std::num::ParseIntError),
17    NotFound(String),
18    Validation(String),
19}
20
21impl From<io::Error> for AppError {
22    fn from(error: io::Error) -> Self {
23        AppError::Io(error)
24    }
25}
26
27// Using custom error type
28fn read_number_from_file(path: &str) -> Result<i32, AppError> {
29    let contents = read_file(path)?;  // Auto-converts io::Error
30    let number = contents.trim().parse()
31        .map_err(AppError::Parse)?;   // Explicitly convert ParseIntError
32    Ok(number)
33}
34
35// Option for nullable values
36fn find_user(id: &str) -> Option<User> {
37    users.iter().find(|u| u.id == id).cloned()
38}
39
40// Combining Option and Result
41fn get_user_age(id: &str) -> Result<u32, AppError> {
42    find_user(id)
43        .ok_or_else(|| AppError::NotFound(id.to_string()))
44        .map(|user| user.age)
45}

Go Error Handling

Explicit Error Returns:

 1// Basic error handling
 2func getUser(id string) (*User, error) {
 3    user, err := db.QueryUser(id)
 4    if err != nil {
 5        return nil, fmt.Errorf("failed to query user: %w", err)
 6    }
 7    if user == nil {
 8        return nil, errors.New("user not found")
 9    }
10    return user, nil
11}
12
13// Custom error types
14type ValidationError struct {
15    Field   string
16    Message string
17}
18
19func (e *ValidationError) Error() string {
20    return fmt.Sprintf("validation failed for %s: %s", e.Field, e.Message)
21}
22
23// Sentinel errors for comparison
24var (
25    ErrNotFound     = errors.New("not found")
26    ErrUnauthorized = errors.New("unauthorized")
27    ErrInvalidInput = errors.New("invalid input")
28)
29
30// Error checking
31user, err := getUser("123")
32if err != nil {
33    if errors.Is(err, ErrNotFound) {
34        // Handle not found
35    } else {
36        // Handle other errors
37    }
38}
39
40// Error wrapping and unwrapping
41func processUser(id string) error {
42    user, err := getUser(id)
43    if err != nil {
44        return fmt.Errorf("process user failed: %w", err)
45    }
46    // Process user
47    return nil
48}
49
50// Unwrap errors
51err := processUser("123")
52if err != nil {
53    var valErr *ValidationError
54    if errors.As(err, &valErr) {
55        fmt.Printf("Validation error: %s\n", valErr.Field)
56    }
57}

Universal Patterns

Pattern 1: Circuit Breaker

Prevent cascading failures in distributed systems.

 1from enum import Enum
 2from datetime import datetime, timedelta
 3from typing import Callable, TypeVar
 4
 5T = TypeVar('T')
 6
 7class CircuitState(Enum):
 8    CLOSED = "closed"       # Normal operation
 9    OPEN = "open"          # Failing, reject requests
10    HALF_OPEN = "half_open"  # Testing if recovered
11
12class CircuitBreaker:
13    def __init__(
14        self,
15        failure_threshold: int = 5,
16        timeout: timedelta = timedelta(seconds=60),
17        success_threshold: int = 2
18    ):
19        self.failure_threshold = failure_threshold
20        self.timeout = timeout
21        self.success_threshold = success_threshold
22        self.failure_count = 0
23        self.success_count = 0
24        self.state = CircuitState.CLOSED
25        self.last_failure_time = None
26
27    def call(self, func: Callable[[], T]) -> T:
28        if self.state == CircuitState.OPEN:
29            if datetime.now() - self.last_failure_time > self.timeout:
30                self.state = CircuitState.HALF_OPEN
31                self.success_count = 0
32            else:
33                raise Exception("Circuit breaker is OPEN")
34
35        try:
36            result = func()
37            self.on_success()
38            return result
39        except Exception as e:
40            self.on_failure()
41            raise
42
43    def on_success(self):
44        self.failure_count = 0
45        if self.state == CircuitState.HALF_OPEN:
46            self.success_count += 1
47            if self.success_count >= self.success_threshold:
48                self.state = CircuitState.CLOSED
49                self.success_count = 0
50
51    def on_failure(self):
52        self.failure_count += 1
53        self.last_failure_time = datetime.now()
54        if self.failure_count >= self.failure_threshold:
55            self.state = CircuitState.OPEN
56
57# Usage
58circuit_breaker = CircuitBreaker()
59
60def fetch_data():
61    return circuit_breaker.call(lambda: external_api.get_data())

Pattern 2: Error Aggregation

Collect multiple errors instead of failing on first error.

 1class ErrorCollector {
 2  private errors: Error[] = [];
 3
 4  add(error: Error): void {
 5    this.errors.push(error);
 6  }
 7
 8  hasErrors(): boolean {
 9    return this.errors.length > 0;
10  }
11
12  getErrors(): Error[] {
13    return [...this.errors];
14  }
15
16  throw(): never {
17    if (this.errors.length === 1) {
18      throw this.errors[0];
19    }
20    throw new AggregateError(
21      this.errors,
22      `${this.errors.length} errors occurred`,
23    );
24  }
25}
26
27// Usage: Validate multiple fields
28function validateUser(data: any): User {
29  const errors = new ErrorCollector();
30
31  if (!data.email) {
32    errors.add(new ValidationError("Email is required"));
33  } else if (!isValidEmail(data.email)) {
34    errors.add(new ValidationError("Email is invalid"));
35  }
36
37  if (!data.name || data.name.length < 2) {
38    errors.add(new ValidationError("Name must be at least 2 characters"));
39  }
40
41  if (!data.age || data.age < 18) {
42    errors.add(new ValidationError("Age must be 18 or older"));
43  }
44
45  if (errors.hasErrors()) {
46    errors.throw();
47  }
48
49  return data as User;
50}

Pattern 3: Graceful Degradation

Provide fallback functionality when errors occur.

 1from typing import Optional, Callable, TypeVar
 2
 3T = TypeVar('T')
 4
 5def with_fallback(
 6    primary: Callable[[], T],
 7    fallback: Callable[[], T],
 8    log_error: bool = True
 9) -> T:
10    """Try primary function, fall back to fallback on error."""
11    try:
12        return primary()
13    except Exception as e:
14        if log_error:
15            logger.error(f"Primary function failed: {e}")
16        return fallback()
17
18# Usage
19def get_user_profile(user_id: str) -> UserProfile:
20    return with_fallback(
21        primary=lambda: fetch_from_cache(user_id),
22        fallback=lambda: fetch_from_database(user_id)
23    )
24
25# Multiple fallbacks
26def get_exchange_rate(currency: str) -> float:
27    return (
28        try_function(lambda: api_provider_1.get_rate(currency))
29        or try_function(lambda: api_provider_2.get_rate(currency))
30        or try_function(lambda: cache.get_rate(currency))
31        or DEFAULT_RATE
32    )
33
34def try_function(func: Callable[[], Optional[T]]) -> Optional[T]:
35    try:
36        return func()
37    except Exception:
38        return None

Best Practices

  1. Fail Fast: Validate input early, fail quickly
  2. Preserve Context: Include stack traces, metadata, timestamps
  3. Meaningful Messages: Explain what happened and how to fix it
  4. Log Appropriately: Error = log, expected failure = don’t spam logs
  5. Handle at Right Level: Catch where you can meaningfully handle
  6. Clean Up Resources: Use try-finally, context managers, defer
  7. Don’t Swallow Errors: Log or re-throw, don’t silently ignore
  8. Type-Safe Errors: Use typed errors when possible
 1# Good error handling example
 2def process_order(order_id: str) -> Order:
 3    """Process order with comprehensive error handling."""
 4    try:
 5        # Validate input
 6        if not order_id:
 7            raise ValidationError("Order ID is required")
 8
 9        # Fetch order
10        order = db.get_order(order_id)
11        if not order:
12            raise NotFoundError("Order", order_id)
13
14        # Process payment
15        try:
16            payment_result = payment_service.charge(order.total)
17        except PaymentServiceError as e:
18            # Log and wrap external service error
19            logger.error(f"Payment failed for order {order_id}: {e}")
20            raise ExternalServiceError(
21                f"Payment processing failed",
22                service="payment_service",
23                details={"order_id": order_id, "amount": order.total}
24            ) from e
25
26        # Update order
27        order.status = "completed"
28        order.payment_id = payment_result.id
29        db.save(order)
30
31        return order
32
33    except ApplicationError:
34        # Re-raise known application errors
35        raise
36    except Exception as e:
37        # Log unexpected errors
38        logger.exception(f"Unexpected error processing order {order_id}")
39        raise ApplicationError(
40            "Order processing failed",
41            code="INTERNAL_ERROR"
42        ) from e

Common Pitfalls

  • Catching Too Broadly: except Exception hides bugs
  • Empty Catch Blocks: Silently swallowing errors
  • Logging and Re-throwing: Creates duplicate log entries
  • Not Cleaning Up: Forgetting to close files, connections
  • Poor Error Messages: “Error occurred” is not helpful
  • Returning Error Codes: Use exceptions or Result types
  • Ignoring Async Errors: Unhandled promise rejections

Resources

  • references/exception-hierarchy-design.md: Designing error class hierarchies
  • references/error-recovery-strategies.md: Recovery patterns for different scenarios
  • references/async-error-handling.md: Handling errors in concurrent code
  • assets/error-handling-checklist.md: Review checklist for error handling
  • assets/error-message-guide.md: Writing helpful error messages
  • scripts/error-analyzer.py: Analyze error patterns in logs

What Users Are Saying

Real feedback from the community

Environment Matrix

Dependencies

No specific dependencies required

Framework Support

Python (FastAPI, Django, Flask) ✓ TypeScript/JavaScript (Node.js, React) ✓ Rust (tokio, serde) ✓ Go (standard library) ✓ Any language with exception handling ✓

Context Window

Token Usage ~3K-8K tokens depending on code complexity and error patterns

Security & Privacy

Information

Author
wshobson
Updated
2026-01-30
Category
architecture-patterns