APICallError: when the provider request itself fails

APICallError is the error you see when the HTTP call to the provider fails: DNS issues, connection resets, 401s, 429s, 500s. It is not a model behavior problem; the request never completed.

import { APICallError, generateText } from 'ai';

try { await generateText({ model: 'your-model-id', prompt: 'Hi' }); } catch (error) { if (APICallError.isInstance(error)) { console.error(error.statusCode, error.url, error.message); return; } throw error; }

What to know:

1. Import from 'ai', not '@ai-sdk/ai' (that package does not exist). Provider code can import it from '@ai-sdk/provider' directly.
2. Prefer APICallError.isInstance(error) over instanceof. The static guard works even when two copies of the SDK are loaded, which instanceof does not.
3. Check statusCode first: 401 means bad key, 429 means rate limited (the SDK retries these automatically up to maxRetries), 404 often means a wrong model id or baseURL.
4. A 401 with a key you are sure is right usually means the key went to the wrong provider: e.g. an OpenAI key sent to the gateway, or vice versa. Check which provider factory you constructed.
5. Timeouts and aborts surface here too. If the user hit stop(), expect an abort-flavored failure, not a provider outage.
6. In v5 the AI prefix was dropped: AIAPICallError became APICallError. Old catch code matching the old name silently stops catching.

Verified against the live AI SDK docs 2026-09-26. The AI SDK errors reference lists APICallError under provider requests and responses, documents importing from 'ai' (not @ai-sdk/ai), and shows the APICallError.isInstance guard pattern with statusCode handling. The v5 migration guide documents the error class renames dropping the AI_ prefix.