How does the SDK handle errors?

How does the SDK handle errors?

The Vercel AI SDK handles errors through a multi-layered approach that includes custom error classes, robust retry logic, and specialized handling for both streaming and UI components.

###1. Custom Error Hierarchy

The SDK uses a structured error system based on a base AISDKError class. This class uses a Symbol-based marking system to ensure isInstance checks work correctly even if multiple versions of the SDK are present in the same project.

• AISDKError: The base class for all AI SDK errors.
• APICallError: Thrown when an API call fails. It includes details like statusCode, url, responseHeaders, and a responseBody. It also has an isRetryable flag.
• Specialized Errors: The SDK defines many specific error types for different failure modes:
  • NoOutputGeneratedError: Thrown when the model returns an empty response.
  • NoSuchToolError: Thrown when a model tries to call a tool that isn't defined.
  • TypeValidationError: Thrown when a structured output (like generateObject) doesn't match the provided schema.
  • RetryError: Thrown when all retry attempts for a call have failed.

###2. Automatic Retries

The SDK includes a built-in retry mechanism (retryWithExponentialBackoff) used by core functions like generateText.

• Exponential Backoff: Retries start with a small delay that increases exponentially.
• Header Awareness: It respects standard HTTP headers like Retry-After and retry-after-ms (common in OpenAI and other providers).
• Configurable: You can customize the maxRetries in most core functions.

###3. Error Handling in Core Functions

Functions like generateText, streamText, generateObject, and streamObject handle errors as follows:

• onError Callback: You can provide an onError callback to log errors or perform side effects.
• Stream Errors: In streaming functions, errors that occur mid-stream are typically emitted as an "error" part in the stream. This prevents the entire stream from crashing and allows the client to handle the partial failure.
• Graceful Failures: If a tool execution fails, the SDK can often continue the conversation by passing the tool error back to the model as a "tool-error" part.

###4. UI Layer Handling (useChat, useCompletion)

In the React, Svelte, and Vue hooks:

• error State: Hooks provide an error object in their return value. If an error occurs during a request or while streaming, this state is updated automatically.
• onError Callback: A callback you can define to handle errors (e.g., showing a toast notification).
• Abort Handling: The SDK distinguishes between manual aborts (via stop()) and actual errors. Aborts do not trigger the error state.
• Automatic Cleanup: The SDK typically resets the error state when a new request is started (e.g., when the user resubmits the form).

###5. Server-to-Client Error Propagation

When using streamText on the server with a UI hook on the client:

1. If the server encounters an error, it sends a specialized "error" chunk over the data stream.
2. The client-side processUIMessageStream utility detects this chunk.
3. It converts the chunk into a JavaScript Error object and triggers the hook's onError callback and updates the error state.

###Example: Catching errors in generateText

import { generateText, APICallError } from 'ai';

try {
  const result = await generateText({
    model: yourModel,
    prompt: 'Hello!',
  });
} catch (error) {
  if (APICallError.isInstance(error)) {
    console.log(error.statusCode); // e.g. 429
    console.log(error.responseBody);
  }
}