Enhanced error handling and debugging capabilities

[jmazzahacks]

Summary

This PR significantly enhances error handling and debugging capabilities for the OpenRouter Python client, making it much easier to diagnose and resolve API-related issues.

Note: This is a clean replacement for PR #5 which included unrelated commits.

Key Features

1. Enhanced APIError Exception

• Comprehensive error details: Captures all available error information from API responses
• Debugging method: get_detailed_error_info() provides formatted error summaries
• Better parsing: Handles multiple error response formats (OpenRouter, OpenAI-style, generic)

2. Improved HTTP Error Handling

• Multiple format support: Handles error, message, detail, reason fields
• Pretty-printed logs: JSON error details with nested structure support
• Raw response preservation: Stores original response for debugging

3. Comprehensive Error Examples

• New examples: Complete demonstrations in docs/examples/error_handling.py
• Real-world scenarios: Authentication, rate limiting, validation errors

Example Enhanced Error Output

ERROR - API Error 400: Provider returned error
ERROR - Error Details:
ERROR -   {
ERROR -     "message": "Provider returned error",
ERROR -     "code": 400,
ERROR -     "metadata": {
ERROR -       "raw": {
ERROR -         "error": {
ERROR -           "message": "Invalid schema: Missing required field",
ERROR -           "type": "invalid_request_error",
ERROR -           "param": "text.format.schema"
ERROR -         }
ERROR -       },
ERROR -       "provider_name": "OpenAI"
ERROR -     }
ERROR -   }

Benefits

• Better debugging: Quickly identify root cause of API issues
• Comprehensive info: All error details captured and presented clearly
• Production ready: Enhanced logging for production debugging
• Future-proof: Handles various error formats from different providers

Files Modified

• src/openrouter_client/exceptions.py - Enhanced APIError class
• src/openrouter_client/http.py - Improved error parsing and logging
• docs/examples/error_handling.py - Comprehensive examples

Contributed by @jmazzahacks