Error Handling Patterns

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.)

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

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

# Good error handling example
def process_order(order_id: str) -> Order:
    """Process order with comprehensive error handling."""
    try:
        # Validate input
        if not order_id:
            raise ValidationError("Order ID is required")

        # Fetch order
        order = db.get_order(order_id)
        if not order:
            raise NotFoundError("Order", order_id)

        # Process payment
        try:
            payment_result = payment_service.charge(order.total)
        except PaymentServiceError as e:
            # Log and wrap external service error
            logger.error(f"Payment failed for order {order_id}: {e}")
            raise ExternalServiceError(
                f"Payment processing failed",
                service="payment_service",
                details={"order_id": order_id, "amount": order.total}
            ) from e

        # Update order
        order.status = "completed"
        order.payment_id = payment_result.id
        db.save(order)

        return order

    except ApplicationError:
        # Re-raise known application errors
        raise
    except Exception as e:
        # Log unexpected errors
        logger.exception(f"Unexpected error processing order {order_id}")
        raise ApplicationError(
            "Order processing failed",
            code="INTERNAL_ERROR"
        ) 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