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: AI_APICallError became APICallError. Old catch code matching the old name silently stops catching.