Error Handling: Exceptions, Retries, and HTTP Mapping

Every error the SDK encounters — network failures, authentication issues, rate limits, invalid requests, missing capabilities — surfaces as a typed exception that extends AiSdkException. Because all exceptions share a common base, you can catch them at a single point or handle each case specifically. The HttpErrorNormalizer maps provider HTTP responses to the correct exception class so your code stays the same regardless of which provider you use.

Base class: `AiSdkException`

AiSdkException extends RuntimeException and carries a $context array populated by the throwing code. All context values are accessible through typed accessor methods:

use AiSdk\Exceptions\AiSdkException;

try {
    $result = Generate::text('Hello')->model($model)->run();
} catch (AiSdkException $e) {
    $e->provider();    // ?string — provider name (e.g. 'openai')
    $e->modelId();     // ?string — model ID used in the request
    $e->status();      // ?int   — HTTP status code, if applicable
    $e->requestId();   // ?string — provider request ID from response headers
    $e->errorType();   // ?string — provider error type string
    $e->errorCode();   // ?string — provider error code string
    $e->retryAfter();  // ?int   — seconds to wait before retrying (from Retry-After header)
    $e->isRetryable(); // bool   — true for statuses 408, 409, 429, 500, 502, 503, 504, 529
    $e->body();        // mixed  — raw response body
    $e->context();     // array  — full context array
}

Exception hierarchy

AiSdkException (RuntimeException)
├── ProviderException                  — base for all provider-originated errors
│   ├── APIConnectionException         — network/connection failure (no HTTP status)
│   └── APIStatusException             — base for HTTP status errors
│       ├── AuthenticationException    — 401
│       ├── PermissionDeniedException  — 403
│       ├── NotFoundException          — 404
│       ├── InvalidRequestException    — 4xx (other 400-range)
│       ├── RateLimitException         — 429
│       ├── OverloadedException        — 529
│       └── InternalServerException    — 5xx
├── CapabilityNotSupportedException    — model lacks required capability
├── NoSuchModelException               — model not found in registry/catalog
├── MissingApiKeyException             — API key not configured
├── InvalidArgumentException           — invalid argument passed to an SDK method
├── ToolExecutionException             — tool handler threw an exception
└── InvalidToolInputException          — tool input validation failed

HTTP status mapping

HttpErrorNormalizer::normalize() maps the HTTP status code from a failed provider response to the appropriate exception class:

Exception	HTTP Status	Description
`AuthenticationException`	401	Invalid or missing API key
`PermissionDeniedException`	403	Access denied to the requested resource
`NotFoundException`	404	Requested resource does not exist
`InvalidRequestException`	4xx	Bad request parameters (other 4xx)
`RateLimitException`	429	Rate limit exceeded
`OverloadedException`	529	Provider is overloaded
`InternalServerException`	5xx	Provider server error
`ProviderException`	other	Any other unexpected status
`APIConnectionException`	—	Network or connection failure
`CapabilityNotSupportedException`	—	Model does not support the required capability
`NoSuchModelException`	—	Model not found in the registry or catalog
`MissingApiKeyException`	—	API key environment variable not set
`ToolExecutionException`	—	A tool handler threw during execution
`InvalidToolInputException`	—	Tool input failed validation

Retryable statuses

isRetryable() returns true for these HTTP statuses:

Request Timeout
Conflict
Too Many Requests
Internal Server Error
Bad Gateway
Service Unavailable
Gateway Timeout
Overloaded (Anthropic)

APIConnectionException (network failure) is not automatically marked retryable because the request may or may not have reached the provider.

Catch patterns

Catch all SDK exceptions

use AiSdk\Exceptions\AiSdkException;
use AiSdk\Generate;

try {
    $result = Generate::text('Summarise this document.')
        ->model($model)
        ->run();
} catch (AiSdkException $e) {
    logger()->error('AI request failed', [
        'provider'  => $e->provider(),
        'status'    => $e->status(),
        'requestId' => $e->requestId(),
        'message'   => $e->getMessage(),
    ]);

    throw $e;
}

Retry on retryable errors

use AiSdk\Exceptions\AiSdkException;
use AiSdk\Generate;

function generateWithRetry(int $maxAttempts = 3): string
{
    $attempt = 0;

    while (true) {
        try {
            return Generate::text('Hello')->model($model)->run()->text;
        } catch (AiSdkException $e) {
            $attempt++;

            if (! $e->isRetryable() || $attempt >= $maxAttempts) {
                throw $e;
            }

            $wait = $e->retryAfter() ?? (2 ** $attempt); // exponential back-off
            sleep($wait);
        }
    }
}

Catch specific exceptions

use AiSdk\Exceptions\RateLimitException;

try {
    $result = Generate::text('Hello')->model($model)->run();
} catch (RateLimitException $e) {
    $retryAfter = $e->retryAfter() ?? 60;
    // Queue the job to retry after $retryAfter seconds.
    dispatch(new RetryJob())->delay(now()->addSeconds($retryAfter));
}

`HttpErrorNormalizer`

Provider adapters call HttpErrorNormalizer::normalize() when they receive a non-2xx response. You don’t need to call this directly, but understanding it helps when writing custom provider adapters.

use AiSdk\Utils\Errors\HttpErrorNormalizer;

$exception = HttpErrorNormalizer::normalize(
    provider:    'openai',
    status:      429,
    body:        ['error' => ['message' => 'Rate limit exceeded.']],
    requestId:   'req_abc123',
    modelId:     'gpt-4o',
    retryAfter:  30,
);

// $exception is a RateLimitException with isRetryable() === true

The normalizer extracts the human-readable message from the response body by checking error.message, error, or message keys, then falls back to a generic "{provider} request failed with status {status}." string.

Exception class reference

Class	Extends	Namespace
`AiSdkException`	`RuntimeException`	`AiSdk\Exceptions`
`ProviderException`	`AiSdkException`	`AiSdk\Exceptions`
`APIStatusException`	`ProviderException`	`AiSdk\Exceptions`
`APIConnectionException`	`ProviderException`	`AiSdk\Exceptions`
`AuthenticationException`	`APIStatusException`	`AiSdk\Exceptions`
`PermissionDeniedException`	`APIStatusException`	`AiSdk\Exceptions`
`NotFoundException`	`APIStatusException`	`AiSdk\Exceptions`
`InvalidRequestException`	`APIStatusException`	`AiSdk\Exceptions`
`RateLimitException`	`APIStatusException`	`AiSdk\Exceptions`
`OverloadedException`	`APIStatusException`	`AiSdk\Exceptions`
`InternalServerException`	`APIStatusException`	`AiSdk\Exceptions`
`CapabilityNotSupportedException`	`AiSdkException`	`AiSdk\Exceptions`
`NoSuchModelException`	`AiSdkException`	`AiSdk\Exceptions`
`MissingApiKeyException`	`AiSdkException`	`AiSdk\Exceptions`
`InvalidArgumentException`	`AiSdkException`	`AiSdk\Exceptions`
`ToolExecutionException`	`AiSdkException`	`AiSdk\Exceptions`
`InvalidToolInputException`	`AiSdkException`	`AiSdk\Exceptions`

Get Started

Core Concepts

Guides

Advanced

Error Handling: Exceptions, Retries, and HTTP Mapping

Base class: `AiSdkException`

Exception hierarchy

HTTP status mapping

Retryable statuses

Catch patterns

Catch all SDK exceptions

Retry on retryable errors

Catch specific exceptions

`HttpErrorNormalizer`

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Documentation Index

​Base class: AiSdkException

​Exception hierarchy

​HTTP status mapping

​Retryable statuses

​Catch patterns

​Catch all SDK exceptions

​Retry on retryable errors

​Catch specific exceptions

​HttpErrorNormalizer

Build docs developers (and LLMs) love

Base class: `AiSdkException`

Exception hierarchy

HTTP status mapping

Retryable statuses

Catch patterns

Catch all SDK exceptions

Retry on retryable errors

Catch specific exceptions

`HttpErrorNormalizer`