APICallError: when the provider request itself fails

TL;DR

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. Check which provider factory you constructed.

Steps

1. 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.
2. import { APICallError, generateText } from 'ai';

3. 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; }

4. What to know:
5. Import from 'ai', not '@ai-sdk/ai' (that package does not exist). Provider code can import it from '@ai-sdk/provider' directly.
6. Prefer APICallError.isInstance(error) over instanceof. The static guard works even when two copies of the SDK are loaded, which instanceof does not.
7. 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.
8. 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.
9. Timeouts and aborts surface here too. If the user hit stop(), expect an abort-flavored failure, not a provider outage.
10. In v5 the AI prefix was dropped: AIAPICallError became APICallError. Old catch code matching the old name silently stops catching.

When to use

You are seeing this: APICallError is the error you see when the HTTP call to the provider fails: DNS issues, connection resets, 401s, 429s, 500s. Use this skill when you run into "APICallError: when the provider request itself fails".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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.