Аварийное переключение

В provider.fallback перечисляются резервные модели, которые пробуются по порядку, когда основная модель падает на стороне провайдера.

Настройка

fallback принимает массив идентификаторов моделей и находится на одном уровне с type внутри provider. Не более 3 моделей; при превышении запрос возвращает 400.

cURL

Terminal


curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

Python

fallback.py


client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "extra_body": {
            "provider": {
                "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"],
            }
        }
    },
)

TypeScript

fallback.ts


await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: {
    provider: {
      fallback: ['openai/gpt-5.5', 'google/gemini-2.5-pro'],
    },
  },
} as any)

В официальных SDK OpenAI extra_body должен присутствовать в теле запроса как буквальный ключ. TypeScript SDK отправляет его ровно так, как он записан в объекте параметров. Аргумент extra_body= в Python SDK сливает своё содержимое с верхним уровнем тела, поэтому ключ нужно вложить на уровень глубже либо передать через заголовок запроса.

Что вызывает переключение

Переключение покрывает только сбои, произошедшие после того, как маршрутизация выбрала канал:

Ситуация	Поведение
Вышестоящий провайдер возвращает ошибку	Переключается — модели из списка пробуются по порядку, возвращается первый успешный ответ
Сбой на этапе маршрутизации (модели не существует либо закреплённый провайдер её не обслуживает)	Переключения нет — запрос завершается сразу

Вторую строку стоит проговорить прямо: если закрепить provider.type за провайдером, который не обслуживает модель, вернётся 400 provider_type_unavailable, а если указать несуществующую модель — 404 model_not_found. Ни то, ни другое до списка резервных моделей не доходит. Какие именно ошибки провайдера вызывают переключение, определяется поведением шлюза, а не фиксированным списком.

Сочетание с закреплённым провайдером

fallback и type можно передавать вместе: type ограничивает, где выполняется основная модель, а fallback отвечает за то, что произойдёт при её сбое:


{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

Полный справочник полей — в разделе Маршрутизация провайдеров.

Частые ошибки

`error.type`	Когда возникает
`invalid_request_error`	В списке `fallback` больше 3 моделей.