Error Handling Patterns

/error-handling-patterns

Build resilient applications with robust error handling that gracefully handles failures and gives excellent debugging signals. The user pastes code or describes a failure mode; deliver rewritten code, error taxonomy designs, and concrete recommendations as chat artifacts. For actively diagnosing a bug that is happening right now, use systematic-debugging.

When to Use

• Implementing error handling in new features
• Designing error-resilient APIs
• 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.).

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

Review Workflow

When the user pastes code for an error-handling review:

1. Map every failure point (I/O, external calls, parsing, concurrency).
2. Flag pitfalls from the list above with line references.
3. Propose a consistent error taxonomy for the module (typed errors, wrapping strategy).
4. Deliver the rewritten code as a chat artifact plus a short rationale per change.

Detailed Patterns and Worked Examples

Language-specific patterns (Python, TypeScript, Rust, Go), retry/circuit breaker implementations, and API error response design live in references/details.md. Read that file when the navigation tier above is insufficient.

Usage

/error-handling-patterns $ARGUMENTS