Improve Error Handling and Exception Hierarchy (Issue #364)

[mxcoppell]

PR: Improve Error Handling and Exception Hierarchy

Overview

This PR implements improvements to the error handling system in the TradeStation API Python wrapper, addressing issue #364. The changes include a comprehensive exception hierarchy, enhanced error handling throughout the client, and detailed documentation.

What was implemented

• Created a comprehensive exception hierarchy with specialized exception types
• Updated HTTP client implementation to use the new exception system
• Added error handling examples and documentation
• Improved method docstrings with exception information
• Bumped version from 1.1.0 to 1.2.0 and updated the CHANGELOG

Implementation Details

Design Approach

The implementation follows a clean hierarchical design with a base exception class and specialized subclasses for different error types. This approach provides:

• More specific error types for better programmatic handling
• Consistent error reporting across the library
• Enhanced debugging information with request IDs, status codes, and validation details

Files Changed

File	Changes
src/tradestation/utils/exceptions.py	Enhanced exception hierarchy with specific error types
src/tradestation/client/http_client.py	Updated error handling throughout request methods
src/tradestation/client/tradestation_client.py	Updated docstrings with exception information
src/tradestation/__init__.py	Added exports for all exception classes and bumped version
examples/QuickStart/error_handling.py	Created example demonstrating error handling patterns
docs/error_handling.md	Added comprehensive error handling documentation
CHANGELOG.md	Updated with version 1.2.0 changes
pyproject.toml	Bumped version to 1.2.0

Exception Hierarchy

classDiagram
    Exception <|-- TradeStationAPIError
    TradeStationAPIError <|-- TradeStationAuthError
    TradeStationAPIError <|-- TradeStationRateLimitError
    TradeStationAPIError <|-- TradeStationResourceNotFoundError
    TradeStationAPIError <|-- TradeStationValidationError
    TradeStationAPIError <|-- TradeStationNetworkError
    TradeStationAPIError <|-- TradeStationServerError
    TradeStationAPIError <|-- TradeStationTimeoutError
    TradeStationAPIError <|-- TradeStationStreamError
    
    class TradeStationAPIError{
        +str message
        +int status_code
        +str request_id
        +original_exception
    }
    class TradeStationAuthError{
        +str message
    }
    class TradeStationRateLimitError{
        +str message
        +float retry_after
    }
    class TradeStationValidationError{
        +str message
        +dict validation_errors
    }

Loading

Error Handling Flow

sequenceDiagram
    participant Client
    participant HttpClient
    participant API
    participant ExceptionMapper
    
    Client->>+HttpClient: make_request()
    HttpClient->>+API: HTTP Request
    API-->>-HttpClient: HTTP Response
    
    alt Response is success (2xx)
        HttpClient-->>Client: Parsed Response
    else Response is error (4xx/5xx)
        HttpClient->>ExceptionMapper: map_http_error(status, data)
        ExceptionMapper-->>HttpClient: Specific Exception
        HttpClient--xClient: Raise Exception
    else Network Error
        HttpClient--xClient: Raise TradeStationNetworkError
    end

Loading

Testing

• Comprehensive tests cover all exception types
• Unit tests for HTTP client error handling
• Edge cases for validation errors and rate limits
• Fixed bug in create_stream method by adding the missing raise_for_status() call

How to test the changes

1. Run the tests:

poetry run pytest

2. Try the error handling example:

cd examples/QuickStart
python error_handling.py

Note: The example demonstrates various error handling patterns including retry logic, specific exception handling, and proper cleanup.

Knowledge Base Updates

• Added patterns for mapping HTTP status codes to exception types
• Documented error handling best practices in the TradeStation API context

Closes #364

[cursor]

✅ BugBot reviewed your changes and found no bugs!

---

Was this report helpful? Give feedback by reacting with 👍 or 👎