Exceptions — Normalized PHP SDK Error Class Hierarchy

AiSdkException (extends RuntimeException)
├── ProviderException                  — provider returned an error response
│   ├── APIStatusException             — provider returned an HTTP error status
│   │   ├── AuthenticationException    — HTTP 401 — invalid or missing credentials
│   │   ├── PermissionDeniedException  — HTTP 403 — insufficient permissions
│   │   ├── NotFoundException          — HTTP 404 — resource not found
│   │   ├── InvalidRequestException    — HTTP 4xx — malformed or invalid request
│   │   ├── RateLimitException         — HTTP 429 — rate limit exceeded
│   │   ├── OverloadedException        — HTTP 529 — provider capacity exceeded
│   │   └── InternalServerException    — HTTP 5xx — provider server error
│   └── APIConnectionException         — network-level failure, no response received
├── CapabilityNotSupportedException    — requested capability not available on model
├── NoSuchModelException               — model ID not recognised by provider
├── NoSuchToolException                — tool name not registered with the SDK
├── MissingApiKeyException             — API key not configured
├── InvalidArgumentException           — invalid argument passed to an SDK method
├── ToolExecutionException             — tool handler threw during execution
├── InvalidToolInputException          — tool input failed validation
├── JsonException                      — JSON decode failed
└── SchemaValidationException          — structured output failed schema validation

use AiSdk\Exceptions\AiSdkException;
use AiSdk\Exceptions\AuthenticationException;
use AiSdk\Exceptions\RateLimitException;
use AiSdk\Exceptions\OverloadedException;
use AiSdk\Exceptions\InternalServerException;
use AiSdk\Exceptions\APIConnectionException;
use AiSdk\Exceptions\CapabilityNotSupportedException;
use AiSdk\Exceptions\MissingApiKeyException;
use AiSdk\Exceptions\ToolExecutionException;
use AiSdk\Exceptions\InvalidToolInputException;

try {
    $result = $ai->text('Explain monads to a 10-year-old.');
} catch (MissingApiKeyException $e) {
    // API key not configured — check environment variable
    echo "Set the {$e->context()['envVar']} environment variable.\n";

} catch (AuthenticationException $e) {
    // HTTP 401 — credentials rejected
    echo "Authentication failed for provider {$e->provider()}: {$e->getMessage()}\n";

} catch (RateLimitException $e) {
    // HTTP 429 — wait and retry
    $wait = $e->retryAfter() ?? 60;
    echo "Rate limited. Retrying in {$wait} seconds...\n";
    sleep($wait);

} catch (OverloadedException | InternalServerException $e) {
    // Transient provider failure — retryable
    if ($e->isRetryable()) {
        echo "Transient error (HTTP {$e->status()}) — safe to retry.\n";
    }

} catch (APIConnectionException $e) {
    // Network failure — no HTTP status available
    echo "Network error: {$e->getMessage()}\n";
    echo "Caused by: " . $e->getPrevious()?->getMessage() . "\n";

} catch (CapabilityNotSupportedException $e) {
    // Model does not support the requested capability
    echo "Capability {$e->context()['capability']} unavailable on {$e->modelId()}.\n";

} catch (ToolExecutionException $e) {
    // A tool handler threw — inspect the chain
    echo "Tool '{$e->context()['tool']}' failed: {$e->getMessage()}\n";
    echo "Original exception: " . $e->getPrevious()?->getMessage() . "\n";

} catch (InvalidToolInputException $e) {
    // Tool input validation failed
    $ctx = $e->context();
    echo "Invalid input for tool '{$ctx['tool']}' at path '{$ctx['path']}'.\n";

} catch (AiSdkException $e) {
    // Catch-all for any other SDK exception
    echo "SDK error [{$e->provider()}]: {$e->getMessage()}\n";

    if ($e->requestId() !== null) {
        echo "Request ID for support: {$e->requestId()}\n";
    }
}