Ошибка 503 model_disabled: что это и как её обработать

Ошибка 503 model_disabled означает, что модель, которую вы запросили, сейчас выключена в Zukko. Остальные модели при этом работают, ключ и баланс в порядке. Ниже — как распознать эту ошибку, где взять список включённых моделей, как переключиться в Claude Code и Cursor и как написать код, который сам перейдёт на запасную модель.

Что означает model_disabled

Ответ сервера выглядит так:

{
  "error": {
    "message": "Модель 'claude-opus-5-5' временно недоступна. Актуальный список: GET /v1/models",
    "type": "service_unavailable",
    "code": "model_disabled",
    "param": "model"
  }
}

• HTTP-статус: 503.
• code: model_disabled — по нему и проверяйте ошибку в коде.
• message: текст для человека; в конец может добавляться строка со ссылкой на поддержку, поэтому не сравнивайте сообщение целиком.

Шлюз отвечает этой ошибкой сам, не передавая запрос провайдеру, поэтому такой запрос не оплачивается.

Не путайте с похожими ошибками:

Список включённых моделей

GET https://api.zukko.pro/v1/models — публичный эндпоинт, ключ для него не нужен. Он возвращает только те модели, которые включены прямо сейчас:

curl -s https://api.zukko.pro/v1/models

{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-5", "object": "model", "created": 1700000000, "owned_by": "zukko"},
    {"id": "gpt-5.6-sol", "object": "model", "created": 1700000000, "owned_by": "zukko"},
    {"id": "glm-5.3-flash", "object": "model", "created": 1700000000, "owned_by": "zukko"}
  ]
}

Только идентификаторы, если установлен jq:

curl -s https://api.zukko.pro/v1/models | jq -r '.data[].id'

Тот же список есть на странице «Модели» в кабинете. Описание эндпоинта — в справке по моделям↗.

Как выбрать замену

Мы не даём рекомендаций вида «эта модель не хуже той»: качество на ваших задачах проверяйте сами. Но есть формальные критерии, которые замена должна выполнять:

• Контекст. Если вы отправляете больше 128K токенов, подойдут только модели с контекстом 1M: claude-opus-5-5, claude-sonnet-5, gpt-5.6-sol, gpt-5.6-luna.
• Эндпоинт. Через /v1/responses (например, в Codex) работают модели Claude и GPT, но не GLM.
• Цена. Сравните по таблице цен: замена может оказаться дороже основной модели.
• Ключ. Если у ключа задан список разрешённых моделей, замена должна в него входить, иначе получите 403 model_not_allowed_for_key.

Любую модель можно вызывать и в OpenAI-, и в Anthropic-формате — шлюз конвертирует запрос, поэтому менять клиент для замены не нужно.

Код с запасной моделью

Пример на OpenAI SDK: список предпочтений, кэш списка включённых моделей на 5 минут и переход к следующей модели при model_disabled. Основная модель пробуется первой при каждом вызове, поэтому, когда её снова включат, код вернётся к ней сам.

import os
import time

import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["OPENAI_API_KEY"],
    max_retries=0,
)

PREFERRED = ["claude-sonnet-5", "gpt-5.6-sol", "claude-opus-5-5"]
_cache = {"models": set(), "at": 0.0}

Пояснения:

• max_retries=0 отключает встроенные повторы SDK: повторять запрос к выключенной модели бессмысленно.
• error_code достаёт code из тела ошибки; функция работает и с исключениями Anthropic SDK.
• Если вы используете Anthropic SDK, base URL в нём — https://api.zukko.pro без /v1, а логика остаётся той же. Подробнее — в руководстве по Python SDK↗.
• Логируйте, какая модель реально ответила: если ответы обслуживает запасная модель, это стоит видеть в мониторинге.

Claude Code: как сменить модель

Claude Code подключается к Zukko через переменные ANTHROPIC_BASE_URL=https://api.zukko.pro и ANTHROPIC_AUTH_TOKEN=fetch_.... Сменить модель можно тремя способами:

• прямо в сессии командой /model claude-sonnet-5;
• при запуске: claude --model claude-sonnet-5;
• через переменную окружения перед запуском:

export ANTHROPIC_MODEL=claude-sonnet-5
claude

Если модель прописана в переменной окружения или в настройках, после её выключения обновите значение — иначе каждая сессия будет начинаться с ошибки. Подробная настройка — в инструкции для Claude Code↗.

Cursor и другие IDE

В Cursor модель, подключённая через Zukko, задаётся в настройках моделей по имени. Если она выключена, добавьте или выберите другую модель из списка GET /v1/models с тем же ключом и base URL https://api.zukko.pro/v1. Названия пунктов меню в Cursor меняются от версии к версии, поэтому сверяйтесь с нашей инструкцией для Cursor↗ и документацией самого редактора. В Cline, Roo Code и Kilo Code — то же самое: поменяйте поле с идентификатором модели в настройках провайдера.

Частые вопросы

Как часто модели выключают и надолго ли?

Предсказать это заранее нельзя. Поэтому полезно не держать в коде единственную модель без запасной и проверять список GET /v1/models перед выбором. Новости сервиса публикуются в Telegram-канале @zukkopro↗.

Не останется ли приложение навсегда на запасной модели?

В примере выше — нет: основная модель стоит первой в PREFERRED и пробуется при каждом вызове, как только снова появится в списке включённых моделей (кэш обновляется раз в 5 минут или сразу после ошибки).

Списываются ли деньги за запрос с ошибкой model_disabled?

Нет. Шлюз отвечает этой ошибкой сам, не отправляя запрос провайдеру, поэтому токены не тратятся.

Что делать, если выключены все модели из моего списка?

Код из примера в этом случае поднимет понятное исключение. Дальше всё зависит от приложения: поставьте задачу в очередь и повторите позже, покажите пользователю сообщение или расширьте список PREFERRED моделями, которые подходят по контексту и формату. Если ключ ограничен списком моделей, не забудьте добавить новые модели и туда на странице ключей↗.