error-handling-patterns

SKILL.md

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

Fail Fast: Validate input early, fail quickly

Preserve Context: Include stack traces, metadata, timestamps

Meaningful Messages: Explain what happened and how to fix it

Log Appropriately: Error = log, expected failure = don't spam logs

Handle at Right Level: Catch where you can meaningfully handle

Clean Up Resources: Use try-finally, context managers, defer

Don't Swallow Errors: Log or re-throw, don't silently ignore

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