Custom Exception Hierarchies

Why Not Just Use Built-in Exceptions?

Python provides a rich set of built-in exceptions like ValueError, KeyError, and ConnectionError. It's a common mistake to either create custom exceptions for everything or, conversely, to only use these built-in types. A professional approach requires a balance.

The key principle is to create custom exceptions when you need to represent a domain-specific problem that requires a unique handling strategy. A ValueError tells you what happened (an argument had the right type but an inappropriate value), but it doesn't tell you the business context. Was it an invalid trade size, an unsupported ticker symbol, or something else?

To frame this, let's explore a more nuanced perspective on when and why to create custom exceptions.

As the article suggests, we should use built-in exceptions for general programming errors. However, for our trading framework, we need to handle specific failures like:

• The broker's API key is invalid.
• Market data for a specific option contract is missing a bid price.
• An order to open a credit spread is rejected due to insufficient margin.

Catching a generic Exception for all these cases would force us into messy if/elif/else blocks trying to parse error strings. A custom exception hierarchy solves this elegantly.

Designing the Exception Hierarchy

A well-designed hierarchy provides structure and allows us to catch errors at different levels of granularity. The foundation of this is a single base exception for our entire application. All other custom exceptions will inherit from this base class.

This has two main benefits:

1. It clearly namespaces our application's errors, distinguishing them from Python's built-in errors or third-party library errors.
2. It provides a single "catch-all" for any error originating from our framework (except TradingSystemError:), which can be useful at the highest level of the application for graceful shutdowns.

Let's start by defining our base exception and the top-level categories for our trading system, which directly correspond to the major components we'll be building.

# In a new file, e.g., 'framework/exceptions.py'

class TradingSystemError(Exception):
    """Base exception for all errors in the trading framework."""
    pass

class APIError(TradingSystemError):
    """For errors related to broker API communication."""
    pass

class DataError(TradingSystemError):
    """For errors related to market data processing."""
    pass

class OrderError(TradingSystemError):
    """For errors related to order management and execution."""
    pass

Now, we can get more specific by subclassing these categories.

# Continuing in 'framework/exceptions.py'

# --- API Errors ---
class AuthenticationError(APIError):
    """Failed to authenticate with the broker API."""
    pass

class ConnectionError(APIError):
    """Network-related error when connecting to the API."""
    pass

# --- Data Errors ---
class DataValidationError(DataError):
    """Incoming data failed a validation check."""
    pass

class MissingDataError(DataError):
    """Expected data was not found or is incomplete."""
    pass

# --- Order Errors ---
class OrderRejectedError(OrderError):
    """The broker rejected an order."""
    pass

class InsufficientFundsError(OrderError):
    """Not enough capital or margin to place an order."""
    pass

This structure allows us to handle errors with precision. For example, in our execution handler:

try:
    # code to submit an order
    pass
except InsufficientFundsError as e:
    # specific logic: log a warning, notify user, stop trying for this symbol
    logger.warning(f"Cannot place order due to insufficient funds: {e}")
except OrderRejectedError as e:
    # specific logic: log an error, investigate the broker's reason
    logger.error(f"Order was rejected by the broker: {e}")
except APIError as e:
    # general API logic: maybe the connection is down, try to reconnect
    logger.critical(f"A severe API error occurred: {e}")

Making Exceptions Useful: Adding Context

An exception class is not just a name; it's a container for valuable information about what went wrong. To make debugging effective, our exceptions should carry context.

For example, an OrderRejectedError should include the order_id and the reason provided by the broker. A DataValidationError should specify which data field was invalid.

Let's see how to add this information.

Applying these patterns, we can enhance our OrderRejectedError:

class OrderRejectedError(OrderError):
    """The broker rejected an order."""
    def __init__(self, message, order_id=None, broker_message=None):
        full_message = f"{message} (Order ID: {order_id})"
        super().__init__(full_message)
        self.order_id = order_id
        self.broker_message = broker_message

    def __str__(self):
        # Overriding __str__ for a clean, readable output
        base = super().__str__()
        if self.broker_message:
            return f"{base} | Broker Response: '{self.broker_message}'"
        return base

# --- How you would raise it ---
# raise OrderRejectedError(
#     "Spread order for SPY failed validation",
#     order_id="12345",
#     broker_message="Invalid combo order leg price"
# )

Best Practices: Chaining and Logging

When you catch a low-level exception (e.g., from a networking library) and raise your own higher-level custom exception, you risk losing the original error's traceback. Exception chaining solves this. By using raise NewException from original_exception, you preserve the full context for debugging.

import requests

# ... inside your API connection module
try:
    response = requests.get("https://api.broker.com/account", timeout=5)
    response.raise_for_status() # Raises HTTPError for 4xx/5xx responses
except requests.exceptions.Timeout:
    # Handle a timeout specifically
    raise ConnectionError("API request timed out") from None # 'from None' hides the requests exception
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        # Raise our custom auth error, but link the original HTTPError
        raise AuthenticationError("API authentication failed. Check API keys.") from e
    else:
        # Raise a generic API error for other HTTP issues
        raise APIError(f"API returned an error: {e.response.status_code}") from e

This practice is invaluable. When our logger (from the last lesson) captures the AuthenticationError, it will also include the full traceback from the underlying requests.exceptions.HTTPError, telling us exactly what went wrong at the network level.

Conclusion

In this lesson, we have designed a clean, hierarchical exception system tailored to our trading framework. This is the final foundational piece of Module 1, working hand-in-hand with our configuration and logging systems to create a robust application backbone.

Key Takeaways:

• Create a Base Exception: Start with a single TradingSystemError to namespace all application-specific errors.
• Build a Hierarchy: Design categories of exceptions (APIError, DataError, OrderError) that reflect the domains of your application, allowing for handling at different levels of specificity.
• Add Context: Enhance your custom exceptions by adding relevant data (e.g., order_id, status_code) to make them powerful tools for debugging and programmatic handling.
• Use Exception Chaining: Preserve the root cause of errors by using raise NewException from original_exception, which is critical for effective logging and debugging.
• Handle, Don't Just Catch: The purpose of this hierarchy is to enable intelligent responses to errors, rather than simply catching Exception and giving up.

Preview of the Next Module:
We have now completed the foundational setup of our framework. In the next module, "Broker Connectivity and Data Model," we will put our new APIError hierarchy to immediate use. Our first task will be to implement a connection manager for the Interactive Brokers API, where we will have to gracefully handle the very authentication and connection errors we designed exceptions for today.