[FEATURE] Typed Exception System with Detailed Error Context

[orenlab]

📋 Description

Implement a comprehensive typed exception system that provides detailed error context, improves debugging experience, and enables better error recovery strategies.

🎯 Objectives

• Create hierarchical exception class structure
• Add detailed error context and metadata
• Implement HTTP status code mapping
• Classify retry-able vs non-retryable errors
• Enable error serialization for logging

📝 Detailed Requirements

Exception Hierarchy:

class PyOutlineAPIError(Exception):
    """Base exception for all PyOutlineAPI errors"""
    
class ConnectionError(PyOutlineAPIError):
    """Network and connection related errors"""
    
class AuthenticationError(PyOutlineAPIError):
    """Authentication and authorization errors"""
    
class ValidationError(PyOutlineAPIError):
    """Request validation errors"""
    
class ServerError(PyOutlineAPIError):
    """Server-side errors (5xx responses)"""
    
class RateLimitError(PyOutlineAPIError):
    """Rate limiting errors (429 responses)"""
    
class TimeoutError(ConnectionError):
    """Request timeout errors"""

Error Context Structure:

class PyOutlineAPIError(Exception):
    def __init__(self, message, *, 
                 error_code=None, 
                 http_status=None,
                 request_id=None,
                 endpoint=None,
                 retry_after=None,
                 details=None):
        self.message = message
        self.error_code = error_code
        self.http_status = http_status
        self.request_id = request_id
        self.endpoint = endpoint
        self.retry_after = retry_after
        self.details = details or {}
        self.timestamp = datetime.utcnow()

Features to Implement:

1. Exception Classification

   • HTTP status code to exception mapping
   • Retry-able vs permanent error classification
   • Error severity levels
   • Error category tagging

2. Rich Error Context

   • Request metadata (ID, endpoint, method)
   • Response metadata (status, headers, body)
   • Timing information
   • User-friendly error messages

3. Error Recovery Support

   • Retry-after header parsing
   • Backoff strategy suggestions
   • Circuit breaker integration
   • Error aggregation for monitoring

4. Serialization Support

   • JSON serialization for logging
   • Error details for debugging
   • Sanitized output for user display
   • Structured error responses

🧪 Acceptance Criteria

• All API errors map to appropriate exception types
• Exception details include sufficient debugging information
• Error classification enables automatic retry logic
• Backward compatibility maintained for existing error handling
• Error serialization works with logging infrastructure
• Documentation covers all exception types and handling

📋 Error Mapping Examples

# HTTP Status to Exception mapping
{
    400: ValidationError,
    401: AuthenticationError,
    403: AuthenticationError,
    404: ValidationError,
    408: TimeoutError,
    429: RateLimitError,
    500: ServerError,
    502: ConnectionError,
    503: ServerError,
    504: TimeoutError
}

🧪 Testing Requirements

• Unit tests for all exception types
• Error serialization/deserialization tests
• HTTP status code mapping tests
• Error context preservation tests
• Integration tests with retry logic

📚 Documentation Requirements

• Exception hierarchy reference
• Error handling best practices
• Troubleshooting guide by error type
• Migration guide for existing error handling
• Examples for common error scenarios

🔗 Integration Points

• Integrates with Issue [FEATURE] Advanced Connection Management with Pooling and Recovery #8 (Connection recovery)
• Supports Issue [FEATURE] Comprehensive Observability with OpenTelemetry Integration #9 (Error metrics and logging)
• Enables better debugging for all API operations

[orenlab]

Added in #12