Summary

Replace generic APIError with specific exception types (AuthenticationError, RateLimitError, ValidationError, NetworkError, etc.)

• Add comprehensive error context with error codes, suggestions, and debug info
• Implement HTTP status code to exception mapping for automatic error classification
• Update api_error_handler decorator to use new structured exceptions
• Add 57 comprehensive tests covering all exception scenarios
• Update client method docstrings to reference specific exception types
• Maintain backward compatibility with deprecated APIError class
• Enable better error recovery patterns and user feedback

Resolves: #3270

Description

This PR implements structured exception classes to replace the generic APIError with specific, actionable exceptions that provide better context for debugging and user feedback. The implementation enables developers to implement proper error recovery patterns, show meaningful errors to users, and improves monitoring capabilities.

Key improvements:

• 10 specific exception types with clear inheritance from base MemoryError
• Automatic HTTP status code mapping (400→ValidationError, 429→RateLimitError, etc.)
• Rich error context including error codes, suggestions, debug info, and retry timing
• Real-world usage patterns matching the exact examples from the GitHub issue

Example usage:

try:
    memory.add(content, user_id=user_id)
except RateLimitError as e:
    time.sleep(e.debug_info.get('retry_after', 60))
except MemoryQuotaExceededError as e:
    logger.error(f"Quota exceeded: {e.error_code}")
except ValidationError as e:
    raise HTTPException(400, detail=e.suggestion)

Fixes #3270

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• Unit Test
• 57 comprehensive tests covering all exception scenarios:
  • Individual exception class testing (initialization, attributes, inheritance)
  • HTTP status code to exception mapping validation
  • api_error_handler decorator integration testing
  • Real-world usage examples from the GitHub issue
  • Backward compatibility testing for existing APIError usage
  • Network error classification (timeout, connection, generic)
  • Rate limit header extraction and retry logic

Test execution:

hatch run dev_py_3_11:pytest tests/test_exceptions.py tests/test_client_utils.py -v
# Result: 57 passed, 0 failed

Multi-Python version testing:

• Python 3.10: ✅ 57 passed
• Python 3.11: ✅ 57 passed

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have checked my code and corrected any misspellings

Maintainer Checklist

• closes Enhance error handling with structured exception classes #3270
• Made sure Checks passed