"""
ProjectX Custom Exceptions
Author: @TexasCoding
Date: 2025-08-02
Overview:
Defines custom exception classes for the ProjectX API client. Provides
comprehensive error handling with categorized exceptions for different
types of errors, including authentication, network, data validation,
and trading-specific errors.
Key Features:
- Hierarchical exception structure with base ProjectXError
- Categorized exceptions for different error types
- Error code support for programmatic error handling
- Response data preservation for debugging
- Comprehensive error context and metadata
- Type-safe exception handling across the SDK
Exception Categories:
- Authentication: Login, token, and permission errors
- Connection: Network, timeout, and SSL errors
- Server: Server-side errors and API issues
- Client: Client-side errors and invalid requests
- Data: Validation, parsing, and format errors
- Trading: Order, position, and instrument errors
Example Usage:
```python
from project_x_py.exceptions import (
ProjectXError,
ProjectXAuthenticationError,
ProjectXRateLimitError,
ProjectXOrderError,
)
try:
await client.authenticate()
except ProjectXAuthenticationError as e:
print(f"Authentication failed: {e}")
print(f"Error code: {e.error_code}")
try:
await order_manager.place_order(...)
except ProjectXRateLimitError as e:
print(f"Rate limit exceeded: {e}")
# Handle rate limiting with retry logic
try:
await client.get_instrument("INVALID")
except ProjectXInstrumentError as e:
print(f"Instrument error: {e}")
# Generic error handling
try:
# API operation
pass
except ProjectXError as e:
print(f"ProjectX error: {e}")
if e.response_data:
print(f"Response data: {e.response_data}")
```
Exception Hierarchy:
- ProjectXError: Base exception for all ProjectX errors
- ProjectXAuthenticationError: Authentication and authorization errors
- ProjectXRateLimitError: Rate limiting and throttling errors
- ProjectXServerError: Server-side errors (5xx status codes)
- ProjectXClientError: Client-side errors (4xx status codes)
- ProjectXConnectionError: Network and connection errors
- ProjectXDataError: Data validation and processing errors
- ProjectXOrderError: Order placement and management errors
- ProjectXPositionError: Position management errors
- ProjectXInstrumentError: Instrument-related errors
Error Handling Features:
- Error code support for programmatic handling
- Response data preservation for debugging
- Comprehensive error context and metadata
- Type-safe exception handling
- Hierarchical error categorization
- Consistent error message formatting
See Also:
- `utils.error_handler`: Error handling decorators and utilities
- `utils.error_messages`: Standardized error messages
"""
from typing import Any
__all__ = [
"InvalidOrderParameters",
"ProjectXAuthenticationError",
"ProjectXClientError",
"ProjectXConnectionError",
"ProjectXDataError",
"ProjectXError",
"ProjectXInstrumentError",
"ProjectXOrderError",
"ProjectXPositionError",
"ProjectXRateLimitError",
"ProjectXServerError",
"RiskLimitExceeded",
]
[docs]
class ProjectXError(Exception):
"""Base exception for ProjectX API errors."""
[docs]
def __init__(
self,
message: str,
error_code: int | None = None,
response_data: dict[str, Any] | None = None,
):
"""
Initialize ProjectX error.
Args:
message: Error message
error_code: Optional error code
response_data: Optional response data from API
"""
super().__init__(message)
self.error_code = error_code
self.response_data = response_data or {}
[docs]
class ProjectXAuthenticationError(ProjectXError):
"""Authentication-related errors."""
[docs]
class ProjectXRateLimitError(ProjectXError):
"""Rate limiting errors."""
[docs]
class ProjectXServerError(ProjectXError):
"""Server-side errors (5xx)."""
class ProjectXClientError(ProjectXError):
"""Client-side errors (4xx)."""
[docs]
class ProjectXConnectionError(ProjectXError):
"""Connection and network errors."""
[docs]
class ProjectXDataError(ProjectXError):
"""Data validation and processing errors."""
[docs]
class ProjectXOrderError(ProjectXError):
"""Order placement and management errors."""
[docs]
class ProjectXPositionError(ProjectXError):
"""Position management errors."""
[docs]
class ProjectXInstrumentError(ProjectXError):
"""Instrument-related errors."""
class RiskLimitExceeded(ProjectXError):
"""Risk limit exceeded errors."""
class InvalidOrderParameters(ProjectXError):
"""Invalid order parameters errors."""