Claude モデルバージョンが見つかりません: 誤ったモデルID、エイリアス、APIルートの修正
Claude model version not found エラーが表示された場合、まずプロンプトを変更するのではなく、3つのことを証明することから始めてください。つまり、現在そのモデルIDが存在すること、エンドポイントがその正確なID形式を期待していること、そして使用しているワークスペースまたはルーターがそれを呼び出す許可を持っていることです。
すばやい修正は、通常次のいずれかです。
| 確認項目 | 何が壊れていたことが多いか | 修正 |
|---|---|---|
| モデルID | 古くなった Claude のハードコードされたスナップショット、 টাইポ、または別プロバイダーからコピーしたモデル名 | 現在の Anthropic モデル一覧を確認したうえで、claude-sonnet-5-5、claude-opus-5-5、claude-haiku-5-5、または claude-fable-5-1 のような最新の Claude API エイリアスに置き換えます。 |
| エンドポイント契約 | Bedrock、Vertex、Azure、OpenAI互換、またはゲートウェイ固有の ID を、別の API に送っていた | 呼び出しているエンドポイントに合わせてモデル文字列を一致させます。 |
| ベースURL | SDK が間違った base_url、パス、またはルートを指している |
クライアントが Anthropic ネイティブの /v1/messages を使用しているのか、OpenAI互換ルートを使用しているのかを確認します。 |
| アクセス | モデルは存在するが、ワークスペース、プロバイダーアカウント、またはサブキーにその使用が許可されていない | 再試行する前に、ワークスペース権限、許可リスト、モデルアクセスを確認します。 |
| ロールアウト状態 | 新しく発表されたモデルはドキュメントには表示されているが、まだルーターやデプロイに存在しない | そのルートをカナリアリリースし、新しいルートが通るまで以前の動作していたモデルを維持します。 |
このガイドでは、本番アプリ、Claude Code のセットアップ、ゲートウェイ、エージェント基盤における claude model version not found、claude model version、claude model versions の失敗に対する実践的なランブックを提供します。
"Claude model version not found" の意味
Claude model version not found は通常、モデル解決の失敗を示す統合レベルの説明です。Anthropic の直接 API エラーは構造化された JSON エラーです。Anthropic は、要求されたリソースが見つからない場合について 404 - not_found_error を文書化しており、そのエラー本文には error.type、error.message、およびリクエストIDが含まれます。Anthropic の Messages API では、プロンプトを完了するモデルを指定する model フィールドも必要です。
この違いは重要です。直接の API レスポンス、SDK 例外、ゲートウェイラッパー、エージェント CLI は、同じ根本的な失敗をそれぞれ異なる言い方で表現することがあります。再試行する前に、元のステータスコード、error.type、message、リクエストID、モデル文字列、エンドポイントパス、ベースURLを保持することがあなたの役目です。
次のトリアージルールを使ってください。
- 404 /
not_found_error: まずエンドポイントパス、モデル識別子、リソースIDを確認します。 - 400 /
invalid_request_error: モデルは存在するが、設定、ツール種別、thinking モード、prefill、またはリクエスト形状を拒否していないか確認します。 - 401 / 403: 認証、ワークスペースアクセス、モデル権限を確認します。
- ゲートウェイ固有の "model version not found": ゲートウェイのモデルカタログと、それがマッピングする下流プロバイダーIDの両方を確認します。
現在の Claude モデルIDの確認
コードを編集する前に、失敗しているモデル文字列を現在の公式一覧と照合してください。この記事のために確認した現行の Anthropic モデルドキュメントでは、表示されている Claude API エイリアスには次のものが含まれます。
| ファミリー | 確認すべき Claude API エイリアス |
|---|---|
| Fable | claude-fable-5-1 |
| Opus | claude-opus-5-5 |
| Sonnet | claude-sonnet-5-5 |
| Haiku | claude-haiku-5-5 |
ブログ記事、UI ラベル、プロバイダーマーケットプレイス、または古いコード例のモデル名が、すべての API 面で有効だと決めつけないでください。Anthropic のドキュメントには、Claude API、Amazon Bedrock、Google Cloud、Microsoft Foundry、そして AWS 上の Claude Platform で別々の ID が示されています。これらの ID は似て見えることがありますが、互換ではありません。
6つの一般的な原因
1. 古くなった Claude モデルバージョンのハードコード
ハードコードされたモデルIDはすぐに陳腐化します。サービスには、次のような古いスナップショットがまだ残っている場合があります。
const model = "claude-3-7-sonnet-20250219";
そのスナップショットをエンドポイントがもう受け付けない場合、またはルーターがそれを一度もマッピングしていない場合、プロンプトが評価される前にリクエストが失敗することがあります。ハードコードされた値を、エンドポイントがサポートする現在のエイリアスに置き換え、複数のファイルに散らばらないよう単一の設定ソースにそのエイリアスを保存してください。
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-5-5";
本番システムでは、設定されたエイリアスと解決されたルートの両方をログに出してください。そうすれば、次回の Claude model version not found インシデントは、コード検索ではなく設定差分で済みます。
2. プロバイダー固有の ID を Claude API に送っていた
プロバイダープラットフォームは独自のモデル識別子を使用します。Bedrock 形式または Vertex 形式の ID は、そのプロバイダーでは有効でも、ネイティブの Claude API に対しては無効な場合があります。逆もまた同様です。ネイティブの Claude API エイリアスは、クラウドプロバイダーのランタイムが期待する完全な識別子ではないことがあります。
このエンドポイント契約表を使用してください。
| 呼び出しているもの | モデルIDは次のようになっているべき | 避けるべきもの |
|---|---|---|
Anthropic Claude API /v1/messages |
Anthropic のドキュメントにある Claude API エイリアス。たとえば claude-sonnet-5-5 |
Bedrock、Vertex、または Foundry のプレフィックス付き ID |
| Amazon Bedrock | プロバイダのドキュメントまたはコンソールに表示される Bedrock のモデルID | SDK が Bedrock ID を想定しているときに使う、Claude 専用のネイティブエイリアス |
| Google Cloud / Vertex | そのデプロイメントに対して表示される Google Cloud のモデルID | 別の環境から貼り付けたネイティブIDや Bedrock ID |
| OpenAI 互換ルーター | ルーターのモデルカタログID | ルーターが明示的に対応していない限り、ネイティブの Anthropic リクエスト形式 |
| Flatkey ルーター | Flatkey のモデルカタログまたはセットアップ手順にある、Flatkey 対応のルート | 散在したプロバイダキーや、未確認のエージェントごとの上書き設定 |
デプロイ先が、直接の Anthropic、クラウドプロバイダのエンドポイント、ルーターにまたがる場合は、設定に小さな変換表を保持してください:
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
正確な文字列は、使用しているプロバイダまたはルーターから取得してください。重要なのは、API の表面を明示することです。
3. ベース URL と SDK が一致していない
Anthropic SDK は Anthropic の Messages API 契約を想定しています。OpenAI 互換ルーターは、Anthropic 互換ルートが文書化されていない限り、OpenAI 互換のクライアントとペイロードを想定します。クライアント、パス、モデルフィールドが混在していると、本当の問題が間違ったルートであっても、Claude モデルバージョンが見つからないように見えることがあります。
次の項目をまとめて確認してください:
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 表面に属しているなら、再試行する前にそれを修正してください。
4. 新しい Claude エイリアスがまだルーターに届いていない
モデルのリリースは、あらゆる SDK、プロキシ、クラウドプロバイダ、ゲートウェイに対して同時に反映されるわけではありません。あるカタログには表示されていても、あなたのルート、許可リスト、またはデプロイメントではまだ使えない場合があります。
本番トラフィックをすぐに切り替えるのではなく、カナリアを使ってください:
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
ここで Flatkey のルーティングと台帳ビューが役立ちます。Claude が多数のモデルのうちの 1 ルートであるなら、個別のプロバイダコンソールや個別のエージェント設定をデバッグする代わりに、1 つのモデルカタログ、1 つのベースルートレビュー、1 つの使用台帳を使ってください。
5. ワークスペース権限またはモデルの許可リストがアクセスをブロックしている
モデル文字列は正しくても、キーがそれを呼び出せない場合があります。これはプロバイダのワークスペース、クラウドアカウント、ルーター、またはサブキー層で起こりえます。
確認してください:
- API キーが、想定しているワークスペースに属しているか。
- そのワークスペースでモデルが有効になっているか。
- ゲートウェイのサブキー、環境キー、またはエージェントキーにモデルの許可リストがあるか。
- ステージングと本番のキーでモデルアクセスが異なっていないか。
- 利用上限やポリシー制御が、権限不足を示すエラーを返していないか。
アクセス失敗を、すべてのキーを広く許可することで解決しないでください。どのエージェントと環境が各 Claude モデルバージョンを呼び出せるかを定義する、狭いポリシーを作成してください。
6. モデルは存在するが、リクエストが未対応のモデル機能を使っている
Anthropic のエラードキュメントには、モデル自体は実在するがリクエストの形が無効な、いくつかの検証失敗が挙げられています。例として、thinking モードの違い、強制ツール使用設定、ツール種別のサポート、新しいモデルでの事前入力済み assistant メッセージなどがあります。
ステータスが 400 invalid_request_error なら、見つからないモデルバージョンを探すのはやめてください。その代わり、リクエスト本文をモデルの現在の機能ルールと照合してください。修正箇所は model ではなく、thinking、tool_choice、ツール宣言、メッセージ履歴の扱いである可能性があります。
本番向けデバッグ実行手順
手順 1: 失敗したリクエストの完全な記録を取得する
何かを編集する前に、最小限のデバッグ記録を保存してください:
{
"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 を使っている場合は、ルート、サブキー、使用台帳の行、そしてフォールバックの判断も記録してください。Anthropic へ直接送っている場合は、Anthropic がサポート対応時にその識別子を求めるため、レスポンスの request-id の値を保持してください。
手順 2: 最小のリクエストで再現する
ツール、長い履歴、画像、キャッシュされた thinking ブロック、フレームワークのラッパーを削除します。まったく同じモデルとキーで、短いメッセージを1つだけテストしてください。
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 と返信してください。"}
]
}'
最小リクエストが動作するなら、そのモデルバージョンはそのキーとエンドポイントで有効です。リクエストの形状のデバッグへ進んでください。同じ not-found 結果で失敗する場合は、モデル文字列、エンドポイント、またはアクセス層に注目してください。
手順 3: モデルIDを1か所で正規化する
Claude のモデルバージョンのために単一の設定ソースを作成します:
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"
そのうえで、アプリケーションコード内での生のモデルIDの使用を禁止します。アプリは claude_default を要求し、新しい Claude モデルバージョンを5つのサービスに貼り付けるべきではありません。
手順 4: エージェントと CI の設定を確認する
Claude モデルバージョンが見つからないエラーは、コード変更ではなく、見落とされた環境変数から発生することがよくあります。以下を確認してください:
.env、.env.production、およびシークレットマネージャーの値。- Claude Code、Cursor、Cline、Roo、Aider、GitHub Actions の変数。
- Docker イメージのデフォルトと Kubernetes の config map。
- 顧客ごと、またはチームごとのサブキーのモデル許可リスト。
- 本番環境へコピーされてしまったローカル開発用の上書き設定。
チームがゲートウェイ経由で Claude Code を使っている場合は、認証とベース URL の設定も確認してください。ANTHROPIC_BASE_URL やキーのスコープが誤っていると、モデル診断のノイズが増えます。認証も失敗している場合は、Claude Code 認証トークンエラーガイドを参照してください。
手順 5: 再試行、フォールバック、または fail closed のどれにするか決める
決定論的な missing-model エラーを永遠に再試行してはいけません。次のポリシーを使ってください:
| Error pattern | Retry? | Fallback? | Human action |
|---|---|---|---|
| Typo or stale model ID | No | Only after config is corrected | Update model registry and redeploy |
| New alias not yet in router | No repeated retries | Keep previous verified model | Open route enablement/canary task |
| Workspace lacks access | No | Maybe, if approved fallback exists | Fix key, workspace, or allowlist |
| 400 request-shape mismatch | No | Not until request is fixed | Patch request body or feature flags |
| 529 overloaded or transient upstream outage | Yes, bounded backoff | Yes, if fallback policy allows | Monitor route health |
一時的な過負荷への対応については、別のランブックを使ってください: API Error 529 overloaded。モデルバージョンの失敗は、通常、設定を変更するまで決定論的です。
Flatkey ルートレビューのチェックリスト
Claude が複数モデルシステムの一部である場合、ルーターがモデル名、キー、許可リスト、費用、フォールバックを確認する単一の場所を提供します。Flatkey の位置づけは、1つのキー、1つの残高、1つの請求書、公式モデルエンドポイント、そしてモデルやツールをまたいだ共有の使用台帳です。
新しい 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 モデルバージョンが見つからないインシデント
- 失敗しているモデル文字列:
- API surface: Anthropic native / router / Bedrock / Vertex / other
- Base URL:
- Request path:
- SDK or client:
- Status code:
- error.type:
- request-id:
- First failing deploy:
- Current official model alias checked:
- Does minimal request pass?
- Is model enabled for this workspace/key/sub-key?
- Is this an unsupported feature error instead of model-not-found?
- Rollback model:
- Owner:
チェックリストは地味なままにしておきましょう。目的は、Claude のモデルバージョンの不足が、各チームが別々の設定を変えるような広範な障害に発展するのを防ぐことです。
よくある質問
「Claude model version not found」は 404 と同じですか？
多くの場合は同じですが、常にそうとは限りません。Anthropic は欠落したリソースに対して 404 - not_found_error を案内していますが、SDK やゲートウェイはメッセージを言い換えることがあります。判断する前に、元のステータスコードと error.type を確認しておきましょう。
どの Claude モデルバージョンを使うべきですか？
呼び出している API またはプロバイダーの画面にある、現在のモデルエイリアスを使ってください。他のクラウドプロバイダー、ルーター、古いコードサンプルの Claude モデルバージョンを、そのエンドポイントのカタログを確認せずに流用しないでください。
エイリアスと日付付きスナップショットのどちらを使うべきですか？
ほとんどのアプリチームにとっては、プロバイダーがサポートされるマッピングを管理するため、現在のエイリアスのほうが運用しやすいです。厳密な再現性が必要な場合は、正確なスナップショット方針、廃止計画、ロールバック手順を文書化してください。
Claude model version not found を Flatkey で自動的に修正できますか？
Flatkey は無効な上流のモデル ID を有効にはできませんが、誤った ID が埋もれる場所を減らすことはできます。Claude が複数のモデルルートのうちの 1 つである場合は、Flatkey を使ってモデルカタログのレビュー、1 つのキーによるルーティング、サブキーの許可リスト、使用ログ、フォールバックポリシーを一元化してください。
いつ別のモデルにフォールバックすべきですか？
フォールバックは、失敗を分類した後に行うのが適切です。 টাইポ、誤ったベース URL、未承認のキーではフォールバックしないでください。現在のルートが利用不可であり、次のルートが同じ入力、品質、コストのチェックを通過しているとポリシーで定められている場合にのみフォールバックしてください。
最終確認
claude model version not found のチケットを閉じる前に、ソース設定、最小限の API スモークテスト、本番ルートのログという 3 つの場所で修正を確認してください。そのうえで、動作確認済みの Claude モデルバージョンをモデルレジストリに追加し、次のデプロイで同じ古い文字列が再導入されないようにしましょう。
すでに複数のモデルをルーティングしている場合は、Flatkey を通して同じ変更をテストし、本番トラフィックが移る前にリクエスト台帳、フォールバックポリシー、モデルの許可リストがすべて一致していることを確認してください。
