AI Gateway
Model Fallbacks
Models & Providers
Add a models array to providerOptions.gateway to list fallback models. The same option works across every AI Gateway API format. Select your API below:
AI Gateway Model Fallbacks
These examples use AI SDK 7 and the AI SDK for Python beta. Set AI_GATEWAY_API_KEY before running them. See API format differences for setup, request fields, and response handling.
Copy page
You can configure model failover to specify backups that are tried in order if the primary model fails or is unavailable.
AI SDK
See the AI SDK model-fallback reference for SDK configuration and usage.
TypeScript
models: ['anthropic/claude-opus-5','google/gemini-3.1-pro-preview'],
Brand & Design
prompt:'Write a haiku about TypeScript.',
const { text } =awaitgenerateText({
providerOptions: {
gateway: {
model:'anthropic/claude-fable-5',
},
});
},
import { generateText } from'ai';
console.log(text);
Combining with provider routing
You can use models together with order to control both model failover and provider preference:
import { streamText } from'ai';
prompt,
gateway: {
model:'openai/gpt-6-astra',
exportasyncfunctionPOST(request:Request) {
constresult=streamText({
models: ['openai/gpt-5.4-nano','anthropic/claude-opus-5'],
},
},
providerOptions: {
const { prompt } =awaitrequest.json();
returnresult.toUIMessageStreamResponse();
order: ['azure','openai'],// Provider preference for each model
This configuration:
- Tries openai/gpt-6-astra via Azure, then OpenAI
- If both fail, tries openai/gpt-5.4-nano via Azure first, then OpenAI
- If those fail, it tries anthropic/claude-opus-5 via available providers
The models and order fields both live under providerOptions.gateway, so you can combine them the same way in the Chat Completions, Messages, OpenAI Responses, and OpenResponses APIs. For all available routing fields, see Provider Options.
How failover works
When processing a request with model fallbacks:
- The gateway routes the request to the primary model (the model parameter)
- For each model, provider routing rules apply (using order or only if specified)
- If all providers for a model fail, the gateway tries the next model in the models array
- The response comes from the first successful model/provider combination
Example provider metadata with model fallbacks
The Python beta can omit routing details from its normalized message metadata. To confirm which model served a request, inspect the raw AI Gateway response or the request logs.
When model fallbacks occur, the modelAttempts array in the provider metadata shows each model that was tried. Each attempt carries two identifiers: canonicalSlug is AI Gateway's normalized model name (always creator/model-name), while modelId is the provider's own internal ID for that model on that provider ( provider:model). These identifiers differ. The same canonicalSlug can be tried via several providers, each reporting its own modelId. Failed models include error details in their providerAttempts, while the successful model includes its provider attempt details:
"success":false,
"canonicalSlug":"google/gemini-3.1-pro-preview",
"attemptNumber":1,
"error":"Internal error encountered.",
"success":false,
},
"statusCode":500
{
"provider":"google",
"error":"Internal error encountered.",
"attemptNumber":2,
"success":false,
"success":true,
"statusCode":500
"providerAttempts": [
"providerResponseId":"msg_01ABCDEFGhJKLmnOpQrStUv"
},
"attemptNumber":1,
"statusCode":200,
"success":true,
Fallbacks in virtual models
Last updated September 10, 2026
Cross-link map: AI Gateway Model Fallbacks (/docs/ai-gateway/models-and-providers/model-fallbacks)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesModel fallbacks now available in Vercel AI GatewayOpenResponses Configuration with AI Gateway — Configure provider routing, fallbacks, and restrictions using the OpenResponses API through AI Gateway.AI Gateway Models and Providers — Choose AI Gateway models and providers. Configure routing, fallbacks, timeouts, prompt caching, reasoning, and web searcOpenAI Chat Completions Configuration with AI Gateway — Configure provider options, model fallbacks, BYOK credentials, and prompt caching through AI Gateway.AI Gateway Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in Vercel AI Gateway.This page links to (4)AI GatewayAI Gateway Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in Vercel AI Gateway.AI Gateway Request Logs — Search, filter, and follow individual AI Gateway requests, inspect provider routing for one request, and export the resuAI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and CoherePages that link here (19)By site: vercel-changelog (3) · vercel-kb (3) · vercel-docs (13)From vercel-changelog Routing rules now available on AI GatewayClaude Fable 5.1 now available on AI GatewayClaude Fable 5 access restored on AI GatewayFrom vercel-kbHow to architect an AI evaluation dashboard on Vercel — Map eval orchestration, traces, and run storage to AI Gateway, Observability, and Marketplace Postgres, and learn when sCost-aware model routing through AI Gateway — Route easy requests to a cheap model and escalate only hard ones to a frontier model through one AI Gateway endpoint, wiHow to build your own AI model router — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatewFrom vercel-docsVercel AI Gateway: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, rTanStack AI with AI Gateway — Connect TanStack AI to Vercel AI Gateway with the official adapter to authenticate requests and stream responses from AIAI Gateway FAQ — Answers to common questions about AI Gateway, including request errors, pricing and markup, SDK and API compatibility, mGetting Started with AI Gateway — Set up AI Gateway with a coding agent, route the agent through AI Gateway, or make your first request with cURL, TypeScrAI Gateway Audio Input — Analyze recorded audio with AI Gateway, compare audio input with transcription and realtime voice, and choose a supporteAI Gateway File and PDF Input — Send PDFs and documents to AI Gateway models with examples for each supported SDK and API format.AI Gateway Video Input — Analyze video clips with AI Gateway using AI SDK 7, Python, Chat Completions, and Responses / OpenResponses.AI Gateway Vision and Image Input — Analyze images with AI Gateway using AI SDK 7, the Python beta, Chat Completions, Messages, and Responses APIs.AI Gateway Models and Providers — Choose AI Gateway models and providers. Configure routing, fallbacks, timeouts, prompt caching, reasoning, and web searcAI Gateway Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in Vercel AI Gateway.AI Gateway Routing Rules — Define team-wide rules that rewrite requests from one model to another or deny specific models in AI Gateway.AI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and CohereAI SDK for Python with AI Gateway — Build AI-powered Python applications using the AI SDK for Python with AI Gateway for unified access to 200+ models.
Can you trust our partners?
Previous
A
virtual model carries its own fallback chain, which replaces the request's models list when set. A vmc/
Provider Options
Was this helpful?
