Claude Model Version Not Found: Исправление неверных model IDs, aliases и API routes
Если вы видите ошибку Claude model version not found, не начинайте с изменения prompt. Сначала проверьте три вещи: существует ли model ID сегодня, ожидает ли ваш endpoint именно такой формат ID, и разрешено ли workspace или router, который вы используете, вызывать его.
Быстрое исправление обычно одно из следующих:
| Проверка | Что обычно сломалось | Исправление |
|---|---|---|
| Model ID | Устаревший hard-coded Claude snapshot, опечатка или скопированное имя модели от другого provider | Замените его на актуальный Claude API alias, например claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5 или claude-fable-5-1, после проверки текущего списка моделей Anthropic. |
| Endpoint contract | В неправильный API был отправлен ID для Bedrock, Vertex, Azure, OpenAI-compatible или gateway-specific | Сопоставьте model string с endpoint, к которому вы обращаетесь. |
| Base URL | SDK указывает на неправильный base_url, path или route |
Подтвердите, использует ли client Anthropic-native /v1/messages или OpenAI-compatible route. |
| Access | Модель существует, но вашему workspace, account провайдера или sub-key не разрешено использовать её | Проверьте permissions workspace, allowlists и access к модели перед повторной попыткой. |
| Rollout state | Недавно анонсированная модель видна в docs, но ещё не присутствует в вашем router или deployment | Проведите canary для route и сохраняйте предыдущую рабочую модель, пока новый route не пройдёт проверку. |
Это руководство даёт практический runbook для сбоев claude model version not found, claude model version и claude model versions в production-приложениях, Claude Code setups, gateways и agent infrastructure.
Что означает "Claude model version not found"
Claude model version not found обычно является описанием на уровне integration сбоя model resolution. Прямые ошибки Anthropic API имеют структуру JSON. Anthropic документирует 404 - not_found_error для запрошенного ресурса, который не может быть найден, а тела ошибок включают error.type, error.message и request ID. Messages API Anthropic также требует поле model, которое указывает model, завершающую prompt.
Это различие важно. Прямой API response, SDK exception, gateway wrapper и agent CLI могут по-разному формулировать один и тот же базовый сбой. Ваша задача — сохранить исходные status code, error.type, message, request ID, model string, endpoint path и base URL до повторной попытки.
Используйте это правило triage:
- 404 /
not_found_error: сначала проверьте path endpoint, model identifier и resource IDs. - 400 /
invalid_request_error: проверьте, существует ли модель, но отклоняет ли она setting, tool type, thinking mode, prefill или shape запроса. - 401 / 403: проверьте authentication, access workspace и permissions модели.
- Gateway-specific "model version not found": проверьте и gateway model catalog, и upstream provider ID, на который он отображается.
Проверка текущего Claude model ID
Перед редактированием кода сравните failing model string с актуальным официальным списком. На момент проверки документации моделей Anthropic для этой статьи видимые Claude API aliases включают:
| Семейство | Claude API alias для проверки |
|---|---|
| Fable | claude-fable-5-1 |
| Opus | claude-opus-5-5 |
| Sonnet | claude-sonnet-5-5 |
| Haiku | claude-haiku-5-5 |
Не предполагайте, что model name из blog post, UI label, provider marketplace или старого code sample действителен для каждого API surface. Документация Anthropic показывает отдельные IDs для Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry и Claude Platform on AWS. Эти IDs могут выглядеть похоже, но они не взаимозаменяемы.
Шесть распространённых причин
1. Устаревшая hard-coded Claude model version
Hard-coded model IDs быстро устаревают. В сервисе всё ещё может быть более старый snapshot, например:
const model = "claude-3-7-sonnet-20250219";
Если endpoint больше не принимает этот snapshot или ваш router никогда не сопоставлял его, запрос может завершиться ошибкой до того, как будет оценён prompt. Замените hard-coded значение на актуальный alias, который поддерживает ваш endpoint, а затем храните этот alias в одном config source, а не в разбросанных файлах.
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-5-5";
Для production systems логируйте и configured alias, и resolved route. Так следующий инцидент Claude model version not found станет diff конфигурации, а не поиском по коду.
2. Provider-specific ID был отправлен в Claude API
Provider platforms используют собственные model identifiers. Bedrock-style или Vertex-style ID может быть допустим на этой platform и недействителен при обращении к native Claude API. Обратное также верно: native Claude API alias может не быть полным identifier, ожидаемым cloud-provider runtime.
Используйте эту таблицу endpoint contract:
| Вы вызываете | Model ID должен выглядеть как | Избегайте |
|---|---|---|
Anthropic Claude API /v1/messages |
Claude API alias из документации Anthropic, например claude-sonnet-5-5 |
Bedrock, Vertex или ID с префиксом Foundry |
| Amazon Bedrock | ID модели Bedrock, указанный в документации провайдера или в консоли | Нативные алиасы только для Claude, когда SDK ожидает Bedrock IDs |
| Google Cloud / Vertex | ID модели Google Cloud, указанный для этого развертывания | Нативные или Bedrock IDs, вставленные из другой среды |
| OpenAI-compatible router | ID каталога моделей этого router'а | Нативные запросы Anthropic, если только router явно не поддерживает их |
| Flatkey router | Маршрут, поддерживаемый Flatkey, из каталога моделей Flatkey или инструкций по настройке | Разрозненные provider keys и непроверенные переопределения на уровне отдельных agents |
Если ваше развертывание охватывает прямой Anthropic, endpoints облачного провайдера и router, храните в конфигурации небольшую таблицу преобразований:
routes:
claude_primary:
api_surface: anthropic_messages
model: claude-sonnet-5-5
claude_gateway:
api_surface: openai_compatible_router
model: claude-sonnet-5-5
claude_bedrock:
api_surface: bedrock
model: anthropic.claude-sonnet-5-5
Точные строки должны поступать от провайдера или router'а, который вы используете. Смысл в том, чтобы явно указать API surface.
3. Базовый URL и SDK не совпадают
Anthropic SDK ожидает контракт Anthropic Messages API. OpenAI-compatible router ожидает OpenAI-compatible client и payload, если только в документации не указано Anthropic-compatible route. Если client, path и поле model смешаны, ошибка может выглядеть как отсутствие версии модели Claude, хотя реальная проблема — неправильный route.
Проверяйте эти поля вместе:
SDK/client: Anthropic SDK, OpenAI SDK, Claude Code, Cursor, Cline, custom HTTP
Base URL: direct provider, router, staging proxy, local mock
Path: /v1/messages, /v1/chat/completions, provider-specific runtime path
Model ID format: native Claude alias, cloud-provider ID, router catalog ID
Auth header: x-api-key, Authorization: Bearer, provider-specific signing
Если одна строка относится к другому API surface, исправьте это перед повторной попыткой.
4. Новый alias Claude еще не дошел до вашего router'а
Запуски моделей не являются атомарными для каждого SDK, proxy, облачного провайдера и gateway. Модель может появиться в одном каталоге раньше, чем ваш route, allowlist или deployment начнет ее поддерживать.
Используйте canary вместо немедленного переключения production traffic:
model_canary:
candidate_model: claude-sonnet-5-5
previous_model: claude-sonnet-5
checks:
- minimal non-streaming request
- streaming request if your app streams
- tool-call request if your app uses tools
- token-count or dry-run path if available
- billing and usage ledger row
rollout:
start: 1%
promote_when: 100 successful requests and no model-resolution errors
rollback_on: any repeated not_found_error or route mismatch
Именно здесь помогают routing и ledger view Flatkey. Если Claude — лишь один route среди многих моделей, используйте один catalog моделей, один review базового route и один usage ledger вместо отладки отдельных консолей провайдеров и отдельных конфигураций agents.
5. Права workspace или allowlist моделей блокируют доступ
Иногда строка модели корректна, но ваш key не может вызвать ее. Это может происходить на уровне workspace провайдера, cloud account, router или sub-key.
Проверьте:
- Принадлежит ли API key тому workspace, который вы ожидаете.
- Включена ли модель для этого workspace.
- Есть ли у gateway sub-key, environment key или agent key allowlist моделей.
- Отличаются ли ключи staging и production по доступу к моделям.
- Возвращают ли лимиты расходов или policy controls ошибку, похожую на ошибку разрешений.
Не решайте проблемы доступа путем расширения каждого key. Создайте узкую policy, которая определяет, какие agents и environments могут вызывать каждую версию модели Claude.
6. Модель существует, но ваш запрос использует неподдерживаемые возможности модели
В документации ошибок Anthropic перечислено несколько сбоев валидации, где модель реальна, но форма запроса некорректна. Примеры включают различия в thinking-mode, настройки принудительного использования tools, поддержку типов tools и заранее заполненные assistant messages в новых моделях.
Если статус 400 invalid_request_error, перестаньте искать отсутствующую версию модели. Вместо этого сравните тело запроса с текущими правилами возможностей модели. Исправление может заключаться в изменении thinking, tool_choice, объявлений tools или обработки истории сообщений, а не в изменении model.
Production debug runbook
Шаг 1: Сохраните полную запись проблемного запроса
Сохраните минимальную debug-запись, прежде чем что-либо редактировать:
{
"provider": "anthropic_or_router_name",
"base_url": "https://api.example.com",
"path": "/v1/messages",
"model": "claude-sonnet-5-5",
"sdk": "anthropic-typescript",
"status": 404,
"error_type": "not_found_error",
"request_id": "req_...",
"environment": "production",
"api_key_scope": "prod-agent-key"
}
Если вы используете Flatkey, также зафиксируйте маршрут, sub-key, строку usage-ledger и любое решение о fallback. Если вы используете прямой Anthropic, сохраните значение request-id из ответа, потому что Anthropic запрашивает этот идентификатор в случаях обращения в поддержку.
Шаг 2: Воспроизведите с минимальным запросом
Уберите инструменты, длинную историю, изображения, blocks с cached thinking и обёртки фреймворка. Проверьте одно короткое сообщение с тем же самым model и key.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 64,
"messages": [
{"role": "user", "content": "Ответьте ok."}
]
}'
Если минимальный запрос работает, версия model существует для этого key и endpoint. Переходите к отладке формы запроса. Если он не проходит с тем же результатом not-found, сосредоточьтесь на строке model, endpoint или слое доступа.
Шаг 3: Нормализуйте model IDs в одном месте
Создайте единый источник конфигурации для версий Claude model:
models:
claude_default:
owner: platform
api_surface: anthropic_messages
model: claude-sonnet-5-5
fallback: claude-haiku-5-5
last_verified: "2026-10-10"
claude_reasoning:
owner: agents
api_surface: anthropic_messages
model: claude-opus-5-5
fallback: claude-sonnet-5-5
last_verified: "2026-10-10"
Затем запретите raw model IDs в коде приложения. Приложение должно запрашивать claude_default, а не вставлять новую версию Claude model в пять сервисов.
Шаг 4: Проверьте конфигурацию агента и CI
Ошибки Claude model version not found часто возникают из-за забытой переменной окружения, а не из-за изменения кода. Проверьте:
.env,.env.productionи значения в secret-manager.- Переменные Claude Code, Cursor, Cline, Roo, Aider и GitHub Actions.
- Значения по умолчанию в Docker image и config maps Kubernetes.
- Allowlist моделей для отдельных клиентов или командных sub-key.
- Локальные overrides для разработки, которые были скопированы в production.
Если ваша команда использует Claude Code через gateway, также проверьте настройку auth и base URL. Неверный ANTHROPIC_BASE_URL или scope ключа могут сделать диагностику модели шумной; используйте руководство по ошибкам auth token в Claude Code, если также не проходит аутентификация.
Шаг 5: Решите, retry, fallback или fail closed
Не выполняйте бесконечные retry для детерминированной ошибки отсутствующей модели. Используйте такую политику:
| Шаблон ошибки | Retry? | Fallback? | Действие человека |
|---|---|---|---|
| Опечатка или устаревший model ID | Нет | Только после исправления конфигурации | Обновить реестр моделей и выполнить redeploy |
| Новый alias ещё не добавлен в router | Без повторных retries | Сохранить предыдущую проверенную модель | Открыть задачу на включение маршрута/canary |
| У workspace нет доступа | Нет | Возможно, если существует одобренный fallback | Исправить key, workspace или allowlist |
| Несоответствие формы запроса 400 | Нет | Не до исправления запроса | Исправить body запроса или feature flags |
| 529 перегрузка или временный сбой upstream | Да, с ограниченным backoff | Да, если политика fallback это позволяет | Следить за здоровьем маршрута |
Для обработки временной перегрузки используйте другой runbook: ошибка API 529 overloaded. Сбой версии model обычно является детерминированным, пока вы не измените конфигурацию.
Чеклист ревью маршрута Flatkey
Когда Claude является частью многомодельной системы, router даёт вам одно место для проверки имён моделей, ключей, allowlist, расходов и fallback. Позиционирование Flatkey — один key, один баланс, один счёт, официальные endpoints модели и общий usage ledger для всех моделей и инструментов.
Используйте этот чеклист перед продвижением нового маршрута Claude:
route_review:
route_name: claude_primary
current_model: claude-sonnet-5-5
endpoint_contract: openai_compatible_or_anthropic_native
owner: platform
environments:
dev: verified
staging: verified
production: canary
controls:
sub_key_allowlist: true
request_ledger: true
fallback_policy: explicit
usage_alert: true
rollback:
previous_model: claude-sonnet-5
trigger: repeated model-resolution errors
Для более широкого проектирования маршрутов прочитайте Claude API proxy vs multi-model router и AI model catalog guide. Для компромиссов между стоимостью и маршрутизацией сопоставьте эту статью с Claude API pricing и LLM API fallback routing.
Чеклист инцидента, который можно копировать
Используйте это в Slack, Linear, GitHub или в документе инцидента:
## Инцидент: Claude model version not found
- Строка failing model:
- API surface: Anthropic native / router / Bedrock / Vertex / other
- Base URL:
- Request path:
- SDK or client:
- Status code:
- error.type:
- request-id:
- Первый неуспешный deploy:
- Проверенный текущий официальный model alias:
- Проходит ли minimal request?
- Включена ли модель для этого workspace/key/sub-key?
- Это ошибка unsupported feature, а не model-not-found?
- Rollback model:
- Owner:
Сделайте чек-лист скучным. Цель — не дать отсутствующей версии модели Claude превратиться в масштабный инцидент, когда каждая команда меняет свой отдельный параметр.
Часто задаваемые вопросы
«Claude model version not found» — это то же самое, что 404?
Часто да, но не всегда. Anthropic документирует 404 - not_found_error для отсутствующих ресурсов, тогда как SDK и шлюзы могут переформулировать сообщение. Сохраните исходный код статуса и error.type прежде чем принимать решение.
Какие версии модели Claude мне следует использовать?
Используйте текущие aliases модели из API или интерфейса провайдера, к которому вы обращаетесь. Не копируйте версию модели Claude из другого облачного провайдера, роутера или старого примера кода, не проверив каталог именно этого endpoint’а.
Стоит ли использовать alias или снимок с датой?
Для большинства команд приложений current alias проще в эксплуатации, потому что провайдер управляет поддерживаемым соответствием. Если вам нужна строгая воспроизводимость, задокументируйте точную политику снимков, план вывода из эксплуатации и путь отката.
Может ли Flatkey автоматически исправить Claude model version not found?
Flatkey не может сделать недопустимый upstream model ID допустимым, но может сократить количество мест, где скрываются плохие IDs. Используйте Flatkey, чтобы централизовать проверку каталога моделей, маршрутизацию по одному ключу, allowlist’ы по sub-key, логи использования и fallback-политику, когда Claude — лишь один из маршрутов моделей среди многих.
Когда следует перейти на другую модель при fallback?
Fallback уместен после классификации сбоя. Не выполняйте fallback из-за опечатки, неверного base URL или неавторизованного ключа. Выполняйте fallback, когда ваша политика говорит, что текущий маршрут недоступен, а следующий маршрут прошёл те же проверки на входные данные, качество и стоимость.
Финальная проверка
Прежде чем закрыть тикет claude model version not found, подтвердите исправление в трёх местах: в исходной конфигурации, в минимальном API smoke test и в production route logs. Затем добавьте рабочую версию модели Claude в ваш model registry, чтобы следующее развертывание не вернуло ту же устаревшую строку.
Если вы уже маршрутизируете несколько моделей, проверьте то же изменение через Flatkey, чтобы ваш request ledger, fallback-политика и model allowlists совпали до того, как production traffic начнёт переход.
