Enhancement: Improve Error Handling Developer Experience

[Ref34t]

Problem

Current error messages lack actionable guidance, making debugging and configuration difficult:

// Current: Generic, unclear
throw new InvalidArgumentException('Provider not registered: openai');
// Developer has to figure out: What providers exist? How to register them?

Proposed Solution

Add utilities for consistent, actionable error messages while maintaining full backward compatibility:

// Enhanced: Clear guidance
throw ErrorFactory::providerNotFound('openai', ['anthropic', 'google']);
// Output: Provider "openai" is not registered. 
//         Available providers: anthropic, google
//         Use ProviderRegistry::registerProvider() to register the provider.

Key Components

1. ErrorFactory for Consistent Messages

File: src/Error/ErrorFactory.php (new)

class ErrorFactory
{
    public static function providerNotFound(string $id, array $available = []): InvalidArgumentException
    public static function providerNotConfigured(string $id, array $envVars = []): RuntimeException  
    public static function httpError(string $provider, int $status, string $msg): EnhancedResponseException
}

2. Enhanced HTTP Error Context

File: src/Error/EnhancedResponseException.php (new, extends existing ResponseException)

class EnhancedResponseException extends ResponseException
{
    public function isAuthenticationError(): bool { return $this->httpStatus === 401; }
    public function shouldRetry(): bool { return $this->isServerError() || $this->isRateLimitError(); }
}

3. Application Error Handler

File: src/Error/AiClientErrorHandler.php (new)

// For WordPress plugins, CLI tools, etc.
$errorData = AiClientErrorHandler::handleError($exception);
// Returns: ['type' => 'auth_error', 'recoverable' => false, 'suggestions' => [...]]

Benefits

• Faster debugging - Clear guidance instead of generic messages
• Better CLI experience - Helpful suggestions for resolution
• Application integration - Rich context for WordPress plugins, etc.
• Reduced support burden - Self-explanatory error messages
• Zero breaking changes - All existing code continues to work

Implementation

ErrorFactory + enhanced CLI errors

• New files: src/Error/ErrorFactory.php
• Modified: src/Providers/ProviderRegistry.php, cli.php

Enhanced HTTP exceptions + application utilities

• New files: src/Error/EnhancedResponseException.php, src/Error/AiClientErrorHandler.php
• Modified: Provider implementations for consistent HTTP error handling

Backward Compatibility

// Existing code - no changes needed
try {
    $provider = $registry->getProvider('openai');
} catch (InvalidArgumentException $e) {
    error_log($e->getMessage()); // Still works exactly the same
}

// New code can leverage enhancements  
try {
    $provider = $registry->getProvider('openai');
} catch (InvalidArgumentException $e) {
    $errorData = AiClientErrorHandler::handleError($e); // Rich context available
}

Request for Feedback

1. Would this approach solve pain points you've experienced?
2. Any specific error scenarios that need prioritization?
3. Concerns with the proposed API design?

[felixarntz]

@Ref34t Thank you for raising this!

I completely agree with the concern, but I think the solution can be simplified. You're already working on a better exception infra in #78, and I think we can incorporate this other portion of DX there too, by simply adding static from* methods to the various *Exception classes.

For example:

• RequestException::fromInvalidParam(string $apiName, string $paramName, string $message = ''): self
• ResponseException::fromMissingData(string $apiName, string $fieldName): self
• RequestException::fromBadRequestResponse(string $apiName, Response $response): self

Those are just some ideas, there are probably a few more that would be helpful. I think the best approach to come up with them would be to look at exceptions currently thrown in the code and find common patterns to simplify / abstract.

[Ref34t]

@felixarntz yeah let's close that and focus on the #78