Skip to content
Docs

AI Gateway Provider Timeouts

You can set per-provider timeouts to trigger fast failover when a provider is slow to respond. If a provider doesn't start responding within the configured timeout, AI Gateway aborts the request and falls back to the next available provider.

Use this for latency-sensitive applications where fast failover beats waiting for a slow provider.

Provider timeouts apply to BYOK (Bring Your Own Key) credentials only. Some providers don't support stream cancellation, so you may still be charged for timed-out requests depending on the provider.

Set provider timeouts

Use the providerTimeouts option in providerOptions.gateway to configure timeouts per provider. Values are in milliseconds.

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.

provider-timeouts.ts
import { streamText } from 'ai';
 
const result = streamText({
  model: 'openai/gpt-6-astra',
  prompt: 'Explain quantum computing in two sentences.',
  providerOptions: {
    gateway: {
      providerTimeouts: {
        byok: {
          openai: 15000,
        },
      },
    },
  },
});
 
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
provider-timeouts_ai.py
import asyncio
import ai
 
async def main():
    model = ai.get_model("openai/gpt-6-astra")
    messages = [ai.user_message("Explain quantum computing in two sentences.")]
    params = ai.InferenceRequestParams(
        extra_body={"providerOptions": {"gateway": {"providerTimeouts": {"byok": {"openai": 15000}}}}}
    )
    async with ai.stream(model, messages, params=params) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)
    print()
 
asyncio.run(main())
provider-timeouts-chat.ts
import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.chat.completions.create({
  model: 'openai/gpt-6-astra',
  messages: [
    {
      role: 'user',
      content: 'Explain quantum computing in two sentences.',
    },
  ],
  // AI Gateway extension fields are not included in the upstream SDK types.
  ...{
    providerOptions: {
      gateway: {
        providerTimeouts: {
          byok: {
            openai: 15000,
          },
        },
      },
    },
  },
  stream: true,
});
 
for await (const event of response) {
  process.stdout.write(event.choices[0]?.delta.content ?? '');
}
provider-timeouts_chat.py
import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.chat.completions.create(
    model="openai/gpt-6-astra",
    messages=[{"role": "user", "content": "Explain quantum computing in two sentences."}],
    extra_body={"providerOptions": {"gateway": {"providerTimeouts": {"byok": {"openai": 15000}}}}},
    stream=True,
)
 
for event in response:
    if event.choices:
        print(event.choices[0].delta.content or "", end="", flush=True)
provider-timeouts-chat.sh
curl --fail-with-body --no-buffer https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in two sentences."
    }
  ],
  "providerOptions": {
    "gateway": {
      "providerTimeouts": {
        "byok": {
          "openai": 15000
        }
      }
    }
  },
  "stream": true
}'
provider-timeouts-messages.ts
import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh',
});
 
const response = await client.messages.create({
  model: 'openai/gpt-6-astra',
  messages: [
    {
      role: 'user',
      content: 'Explain quantum computing in two sentences.',
    },
  ],
  max_tokens: 1024,
  ...{
    providerOptions: {
      gateway: {
        providerTimeouts: {
          byok: {
            openai: 15000,
          },
        },
      },
    },
  },
  stream: true,
});
 
for await (const event of response) {
  if (
    event.type === 'content_block_delta' &&
    event.delta.type === 'text_delta'
  ) {
    process.stdout.write(event.delta.text);
  }
}
provider-timeouts_messages.py
import os
from anthropic import Anthropic
 
client = Anthropic(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh",
)
 
response = client.messages.create(
    model="openai/gpt-6-astra",
    messages=[{"role": "user", "content": "Explain quantum computing in two sentences."}],
    max_tokens=1024,
    extra_body={"providerOptions": {"gateway": {"providerTimeouts": {"byok": {"openai": 15000}}}}},
    stream=True,
)
 
for event in response:
    if event.type == "content_block_delta" and event.delta.type == "text_delta":
        print(event.delta.text, end="", flush=True)
provider-timeouts-messages.sh
curl --fail-with-body --no-buffer https://ai-gateway.vercel.sh/v1/messages \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "openai/gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in two sentences."
    }
  ],
  "max_tokens": 1024,
  "providerOptions": {
    "gateway": {
      "providerTimeouts": {
        "byok": {
          "openai": 15000
        }
      }
    }
  },
  "stream": true
}'
provider-timeouts-responses.ts
import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.responses.create({
  model: 'openai/gpt-6-astra',
  input: 'Explain quantum computing in two sentences.',
  ...{
    providerOptions: {
      gateway: {
        providerTimeouts: {
          byok: {
            openai: 15000,
          },
        },
      },
    },
  },
  stream: true,
});
 
for await (const event of response) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}
provider-timeouts_responses.py
import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.responses.create(
    model="openai/gpt-6-astra",
    input="Explain quantum computing in two sentences.",
    extra_body={"providerOptions": {"gateway": {"providerTimeouts": {"byok": {"openai": 15000}}}}},
    stream=True,
)
 
for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
provider-timeouts-responses.sh
curl --fail-with-body --no-buffer https://ai-gateway.vercel.sh/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-6-astra",
  "input": "Explain quantum computing in two sentences.",
  "providerOptions": {
    "gateway": {
      "providerTimeouts": {
        "byok": {
          "openai": 15000
        }
      }
    }
  },
  "stream": true
}'

These examples set a 15-second timeout for requests using your OpenAI BYOK credentials. If that provider exceeds the timeout, AI Gateway aborts the attempt and tries the next available provider. Configure your BYOK credentials before testing this behavior.

Timeout limits

MinimumMaximum
1,000 milliseconds (1 second)789,000 milliseconds (about 13 minutes)

For streaming requests, AI Gateway clears the timeout when it receives the first stream chunk. For non-streaming requests, the timeout runs until the provider returns the complete response. All examples above use streaming requests.

Combine with provider routing

Provider timeouts work with all other provider options. Combine them with order to control both the provider sequence and failover speed:

app/api/chat/route.ts
import { streamText } from 'ai';
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const result = streamText({
    model: 'anthropic/claude-opus-5',
    prompt,
    providerOptions: {
      gateway: {
        order: ['anthropic', 'bedrock', 'vertex'],
        providerTimeouts: {
          byok: {
            anthropic: 10000,
            bedrock: 15000,
            // no timeout for vertex — uses the default gateway timeout
          },
        },
      },
    },
  });
 
  return result.toUIMessageStreamResponse();
}

This configuration:

  1. Tries Anthropic first with a 10-second timeout
  2. If Anthropic is slow, falls back to Bedrock with a 15-second timeout
  3. If Bedrock is slow, falls back to Vertex with the default gateway timeout

Check timeout behavior in response metadata

When a provider times out, the attempt metadata includes providerTimeout and configuredTimeoutMs fields so you can see exactly what happened. Check the providerAttempts within each modelAttempts entry:

"modelAttempts": [
  {
    "modelId": "anthropic:claude-sonnet-5",
    "canonicalSlug": "anthropic/claude-sonnet-5",
    "success": true,
    "providerAttemptCount": 2,
    "providerAttempts": [
      {
        "provider": "anthropic",
        "credentialType": "byok",
        "success": false,
        "error": "PROVIDER_TIMEOUT",
        "providerTimeout": true,
        "configuredTimeoutMs": 10000
      },
      {
        "provider": "bedrock",
        "credentialType": "byok",
        "success": true,
        "statusCode": 200
      }
    ]
  }
]

For more details on reading provider metadata, see Provider Options.

Timeouts in virtual models

A virtual model can pin provider timeouts for its BYOK providers. The virtual model's values override the request's.

Last updated September 10, 2026
Previous
Model Fallbacks
Next
Automatic Caching

Was this helpful?

supported.