Ошибка model not found означает, что сервер не смог разрешить указанный Model ID в контексте текущего endpoint и API Key. Причиной бывает опечатка, устаревший alias, неправильный протокол, отсутствие доступа или конфигурационный override. Запишите status и request ID, затем проверяйте цепочку от Base URL к ключу и модели. Случайный перебор имён только скрывает исходную ошибку.

Что сохранить до изменения конфигурации

Сначала зафиксируйте небольшую диагностическую карточку:

time: 2026-08-03T12:00:00Z
client: your-client-and-version
protocol: openai-compatible | anthropic-compatible
base_url: https://example.com/v1
model: MODEL_ID_FROM_CONFIG
http_status: 404
provider_code: model_not_found
request_id: req_...

API Key, полный prompt и ответ в карточку не входят. Если ошибка возникла в IDE или agent-инструменте, отдельно запишите имя config-файла и наличие environment variables. Это позволит понять, какое значение реально ушло на сервер.

Хотите повторить диагностику на текущем каталоге моделей? Можно создать собственный аккаунт BetterToken и API Key, сверить endpoint и Model ID с API reference, а затем выполнить один минимальный запрос. Для BetterToken тип endpoint, Base URL, Key group и текущий Model ID должны совпасть; актуальное имя берите из документации или страницы моделей и цен, а результат проверяйте в Dashboard.

Шаг 1. Проверьте Base URL и путь

Посмотрите на итоговый URL запроса, а не только на строку в настройках. SDK может самостоятельно добавить /v1, /models, /chat/completions, /responses или /messages.

Типичные ошибки:

Base URL уже содержит ресурсный путь, а SDK добавляет его второй раз;
/v1 отсутствует или продублирован;
OpenAI-клиент отправляет запрос на Anthropic-compatible адрес;
переменная окружения переопределяет Base URL из config;
приложение использует другой профиль или workspace.

Для BetterToken OpenAI-compatible инструменты используют Base URL с /v1, а Anthropic SDK и Claude Code — адрес без /v1; полный Messages path формируется отдельно. Перед исправлением сверяйте текущую страницу конкретного инструмента.

Шаг 2. Проверьте, какой API Key реально используется

Один и тот же визуальный интерфейс может хранить несколько credentials. Ошибка модели иногда маскирует отсутствие доступа у выбранного ключа.

Проверьте:

credential или environment variable, из которого клиент читает ключ;
отсутствие лишних пробелов и переносов строки;
соответствие ключа протоколу и группе моделей;
не перекрывает ли project config глобальную настройку;
не истёк ли или не был ли отозван ключ.

Не выводите ключ через echo, debug log или screenshot. Для сравнения credentials достаточно безопасного имени профиля либо последних символов fingerprint, если интерфейс сам их показывает.

Шаг 3. Получите текущий Model ID

У OpenAI-compatible endpoint часто есть список моделей. Безопасный диагностический запрос выглядит так:

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Команда использует environment variables и не содержит реального ключа в тексте. Она подходит только когда документация endpoint подтверждает /models.

Для другого протокола или клиента используйте официальный каталог провайдера. Скопируйте поле id без изменения регистра, пробелов и суффиксов. Маркетинговое название модели и API Model ID могут различаться.

Если список открывается, но нужной модели в нём нет, проверьте выбранный ключ и каталог. Если /models сам возвращает ошибку, сначала исправьте endpoint или авторизацию.

Шаг 4. Найдите alias и устаревшую настройку

Model ID может приходить из нескольких мест:

config проекта;
глобальный config клиента;
environment variable;
UI-профиль;
command-line flag;
сохранённая сессия;
routing или model mapping gateway.

Поиск по репозиторию помогает найти старое значение:

rg -n --hidden --glob '!node_modules' --glob '!.git' \
  'OLD_MODEL_ID|model[[:space:]]*=' .

Команда может найти и секретные конфиги. Не публикуйте вывод целиком. Исправляйте только источник, который действительно читает клиент.

В AI-инструментах часто действует приоритет «project config выше global config». После изменения перезапустите клиент или откройте новую сессию, если он кэширует provider settings.

Шаг 5. Отделите ошибку модели от ошибки доступа

HTTP-коды у совместимых API не обязаны совпадать, поэтому смотрите и на тело ошибки.

401: сначала проверьте credential и формат авторизации.
403: модель может существовать, но текущий ключ не имеет доступа.
404: возможны неверный path, endpoint или Model ID.
400: сервер мог отклонить поле model либо другой параметр запроса.
429 / 5xx: это обычно другая категория; не меняйте Model ID без дополнительного сигнала.

Фраза model not found в UI может быть пересказом клиента. Найдите исходный HTTP status, provider code и request ID.

Минимальный повторный тест

После исправления отправьте один короткий запрос без streaming и tools. Для OpenAI-compatible Chat Completions схема может выглядеть так:

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_CURRENT_CATALOG",
    "messages": [{"role": "user", "content": "Reply with OK"}],
    "max_tokens": 8
  }'

Поля и endpoint должны соответствовать документации вашего провайдера. Не переносите этот пример в Anthropic Messages без адаптации.

Успешная проверка состоит из четырёх совпадений:

HTTP status означает успех;
в ответе указан ожидаемый Model ID или его документированный вариант;
request появился в Dashboard;
время, status и usage совпадают с тестом.

Если короткий запрос работает, а IDE продолжает показывать model not found, серверная конфигурация уже исправлена. Ищите override или кэш внутри клиента.

Короткий checklist

Сохранены status, provider code и request ID.
Проверен итоговый URL без двойного /v1 и resource path.
Клиент использует ожидаемый credential.
Model ID взят из текущего каталога.
Проверены project, global и environment override.
Выполнен один минимальный запрос без tools и stream.
Запрос сопоставлен с Dashboard.

Для BetterToken сверяйте API reference и текущий каталог перед заменой Model ID. Это быстрее и безопаснее, чем перебирать похожие названия.

FAQ

Почему модель видна на сайте, но API возвращает model not found?

Возможны другой протокол, Key group, регион каталога, устаревшая сессия или несовпадение маркетингового названия с API ID. Проверьте список моделей именно для текущего credential.

Поможет ли повтор запроса?

При опечатке или неверном endpoint — нет. Сначала исправьте конфигурацию. Retry уместен для временной ошибки только когда status и provider code это подтверждают.

Можно ли сохранить список моделей в config навсегда?

Лучше хранить выбранный ID как управляемую настройку и периодически сверять его с текущим каталогом. Доступность и aliases меняются.

Почему curl работает, а приложение нет?

Приложение может читать другой Base URL, credential или Model ID. Сравните итоговый запрос и проверьте project-level override, environment variables и сохранённый профиль.

Model not found в API: как найти и исправить причину