Claude Model Version Not Found: Perbaiki Wrong Model IDs, Alias, dan API Routes
Jika Anda melihat error Claude model version not found, jangan mulai dengan mengubah prompt. Mulailah dengan membuktikan tiga hal: model ID tersebut memang ada saat ini, endpoint Anda mengharapkan format ID yang persis itu, dan workspace atau router yang Anda gunakan diizinkan untuk memanggilnya.
Perbaikan cepat biasanya salah satu dari ini:
| Pemeriksaan | Apa yang biasanya rusak | Perbaikan |
|---|---|---|
| Model ID | Snapshot Claude hard-coded yang sudah usang, typo, atau nama model yang disalin dari provider lain | Ganti dengan alias Claude API saat ini seperti claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5, atau claude-fable-5-1 setelah memeriksa daftar model Anthropic terbaru. |
| Kontrak endpoint | ID gaya Bedrock, Vertex, Azure, OpenAI-compatible, atau khusus gateway dikirim ke API yang salah | Sesuaikan string model dengan endpoint yang Anda panggil. |
| Base URL | SDK diarahkan ke base_url, path, atau route yang salah |
Konfirmasi apakah client menggunakan Anthropic-native /v1/messages atau route yang kompatibel dengan OpenAI. |
| Akses | Model ada, tetapi workspace, akun provider, atau sub-key Anda tidak diizinkan menggunakannya | Periksa izin workspace, allowlist, dan akses model sebelum mencoba lagi. |
| Status rollout | Model yang baru diumumkan terlihat di dokumentasi tetapi belum tersedia di router atau deployment Anda | Lakukan canary pada route dan pertahankan model yang sebelumnya berfungsi sampai route baru lolos. |
Panduan ini memberi Anda runbook praktis untuk kegagalan claude model version not found, claude model version, dan claude model versions di aplikasi produksi, setup Claude Code, gateway, dan infrastruktur agent.
Apa arti "Claude model version not found"
Claude model version not found biasanya merupakan deskripsi tingkat integrasi dari kegagalan resolusi model. Error langsung dari Anthropic API berbentuk error JSON terstruktur. Anthropic mendokumentasikan 404 - not_found_error untuk resource yang diminta tetapi tidak dapat ditemukan, dan body error-nya menyertakan error.type, error.message, serta request ID. Messages API milik Anthropic juga memerlukan field model yang menamai model yang menyelesaikan prompt.
Perbedaan itu penting. Respons API langsung, pengecualian SDK, wrapper gateway, dan CLI agent semuanya bisa merumuskan kegagalan dasar yang sama dengan cara yang berbeda. Tugas Anda adalah menyimpan status code mentah, error.type, message, request ID, string model, path endpoint, dan base URL sebelum mencoba lagi.
Gunakan aturan triase ini:
- 404 /
not_found_error: periksa dulu path endpoint, identifier model, dan resource ID. - 400 /
invalid_request_error: periksa apakah model memang ada tetapi menolak setting, jenis tool, mode thinking, prefill, atau bentuk request. - 401 / 403: periksa autentikasi, akses workspace, dan izin model.
- "model version not found" khusus gateway: periksa katalog model gateway dan ID provider upstream yang dipetakan.
Pemeriksaan ID model Claude saat ini
Sebelum mengedit kode, bandingkan string model yang gagal dengan daftar resmi terbaru. Berdasarkan dokumentasi model Anthropic yang diperiksa untuk artikel ini, alias Claude API yang terlihat meliputi:
| Family | Alias Claude API yang perlu diverifikasi |
|---|---|
| Fable | claude-fable-5-1 |
| Opus | claude-opus-5-5 |
| Sonnet | claude-sonnet-5-5 |
| Haiku | claude-haiku-5-5 |
Jangan berasumsi nama model dari posting blog, label UI, marketplace provider, atau contoh kode lama valid untuk setiap surface API. Dokumentasi Anthropic menunjukkan ID terpisah untuk Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry, dan Claude Platform on AWS. ID-ID tersebut bisa terlihat mirip, tetapi tidak dapat dipertukarkan.
Enam penyebab umum
1. Versi model Claude hard-coded yang sudah usang
ID model yang di-hard-code cepat menjadi usang. Sebuah layanan mungkin masih berisi snapshot lama seperti:
const model = "claude-3-7-sonnet-20250219";
Jika endpoint tidak lagi menerima snapshot itu, atau router Anda tidak pernah memetakannya, request bisa gagal sebelum prompt dievaluasi. Ganti nilai hard-coded dengan alias saat ini yang didukung endpoint Anda, lalu simpan alias tersebut dalam satu sumber konfigurasi saja, bukan tersebar di banyak file.
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-5-5";
Untuk sistem produksi, log alias yang dikonfigurasi dan route yang ter-resolve. Itu membuat insiden Claude model version not found berikutnya menjadi diff konfigurasi, bukan pencarian kode.
2. ID khusus provider dikirim ke Claude API
Platform provider menggunakan identifier model mereka sendiri. ID gaya Bedrock atau gaya Vertex mungkin valid di provider tersebut dan tidak valid terhadap native Claude API. Sebaliknya juga benar: alias Claude API native mungkin bukan identifier lengkap yang diharapkan runtime cloud provider.
Gunakan tabel kontrak endpoint ini:
| Anda memanggil | ID Model seharusnya terlihat seperti | Hindari |
|---|---|---|
Anthropic Claude API /v1/messages |
Alias Claude API dari dokumentasi Anthropic, misalnya claude-sonnet-5-5 |
ID yang diawali Bedrock, Vertex, atau Foundry |
| Amazon Bedrock | ID model Bedrock yang ditampilkan di dokumentasi provider atau konsol | Alias native khusus Claude saat SDK mengharapkan ID Bedrock |
| Google Cloud / Vertex | ID model Google Cloud yang ditampilkan untuk deployment tersebut | ID native atau Bedrock yang ditempel dari lingkungan lain |
| OpenAI-compatible router | ID katalog model milik router | Bentuk request native Anthropic kecuali router secara eksplisit mendukungnya |
| Flatkey router | Rute yang didukung Flatkey dari katalog model Flatkey atau instruksi penyiapan | Kunci provider yang tersebar dan override per-agent yang belum ditinjau |
Jika deployment Anda mencakup Anthropic langsung, endpoint provider cloud, dan sebuah router, simpan tabel translasi kecil di config:
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
String yang tepat harus berasal dari provider atau router yang Anda gunakan. Intinya adalah membuat permukaan API menjadi eksplisit.
3. Base URL dan SDK tidak cocok
SDK Anthropic mengharapkan kontrak Messages API milik Anthropic. Router yang kompatibel dengan OpenAI mengharapkan client dan payload yang kompatibel dengan OpenAI kecuali mendokumentasikan route yang kompatibel dengan Anthropic. Jika client, path, dan field model tercampur, error bisa terlihat seperti versi model Claude yang hilang padahal masalah sebenarnya adalah route yang salah.
Periksa field-field ini bersama-sama:
SDK/client: Anthropic SDK, OpenAI SDK, Claude Code, Cursor, Cline, custom HTTP
Base URL: provider langsung, router, proxy staging, mock lokal
Path: /v1/messages, /v1/chat/completions, provider-specific runtime path
Model ID format: alias Claude native, ID provider cloud, ID katalog router
Auth header: x-api-key, Authorization: Bearer, provider-specific signing
Jika satu baris berasal dari permukaan API yang berbeda, perbaiki itu sebelum mencoba lagi.
4. Alias Claude baru belum sampai ke router Anda
Peluncuran model tidak bersifat atomik di setiap SDK, proxy, provider cloud, dan gateway. Sebuah model bisa muncul di satu katalog sebelum route, allowlist, atau deployment Anda mendukungnya.
Gunakan canary alih-alih langsung mengalihkan traffic produksi:
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
Di sinilah routing dan tampilan ledger Flatkey membantu. Jika Claude hanyalah satu route di antara banyak model, gunakan satu katalog model, satu review route dasar, dan satu usage ledger alih-alih men-debug konsol provider yang terpisah dan config agen yang terpisah.
5. Izin workspace atau allowlist model memblokir akses
Terkadang string model valid, tetapi key Anda tidak bisa memanggilnya. Hal itu bisa terjadi di workspace provider, akun cloud, router, atau lapisan sub-key.
Periksa:
- Apakah API key milik workspace yang Anda harapkan.
- Apakah model diaktifkan untuk workspace tersebut.
- Apakah gateway sub-key, environment key, atau agent key memiliki allowlist model.
- Apakah key staging dan production memiliki akses model yang berbeda.
- Apakah batas pengeluaran atau kontrol kebijakan mengembalikan error yang berbentuk izin.
Jangan selesaikan kegagalan akses dengan membuka semua key. Buat kebijakan sempit yang menyatakan agen dan lingkungan mana yang boleh memanggil setiap versi model Claude.
6. Model ada, tetapi request Anda menggunakan fitur model yang tidak didukung
Dokumen error Anthropic mencantumkan beberapa kegagalan validasi di mana modelnya nyata tetapi bentuk request tidak valid. Contohnya termasuk perbedaan thinking-mode, pengaturan forced tool-use, dukungan tipe tool, dan pesan assistant yang diprefill pada model yang lebih baru.
Jika statusnya 400 invalid_request_error, berhenti mencari versi model yang hilang. Bandingkan body request dengan aturan kapabilitas terkini model tersebut. Perbaikannya mungkin mengubah thinking, tool_choice, deklarasi tool, atau penanganan riwayat pesan, bukan mengubah model.
Runbook debug produksi
Langkah 1: Tangkap catatan request gagal secara lengkap
Simpan catatan debug minimal sebelum Anda mengubah apa pun:
{
"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"
}
Jika Anda menggunakan Flatkey, catat juga route, sub-key, baris usage-ledger, dan keputusan fallback apa pun. Jika Anda menggunakan Anthropic langsung, simpan nilai request-id dari respons karena Anthropic meminta pengenal itu dalam kasus dukungan.
Langkah 2: Reproduksi dengan permintaan sekecil mungkin
Hapus tools, riwayat panjang, gambar, blok cached thinking, dan pembungkus framework. Uji satu pesan singkat dengan model dan key yang persis sama.
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": "Balas dengan ok."}
]
}'
Jika permintaan minimal berhasil, versi model tersebut ada untuk key dan endpoint itu. Lanjutkan ke debugging bentuk permintaan. Jika gagal dengan hasil tidak ditemukan yang sama, fokus pada string model, endpoint, atau lapisan akses.
Langkah 3: Normalisasi ID model di satu tempat
Buat satu sumber konfigurasi untuk versi model 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"
Kemudian blokir ID model mentah di kode aplikasi. Aplikasi harus meminta claude_default, bukan menempelkan versi model Claude baru ke lima layanan.
Langkah 4: Periksa konfigurasi agent dan CI
Error Claude model version not found sering kali berasal dari variabel lingkungan yang terlupa, bukan perubahan kode. Periksa:
.env,.env.production, dan nilai secret-manager.- Variabel Claude Code, Cursor, Cline, Roo, Aider, dan GitHub Actions.
- Default image Docker dan config maps Kubernetes.
- Allowlist model sub-key per pelanggan atau per tim.
- Override pengembangan lokal yang disalin ke produksi.
Jika tim Anda menggunakan Claude Code melalui gateway, periksa juga pengaturan auth dan base URL. ANTHROPIC_BASE_URL yang salah atau scope key yang salah dapat membuat diagnosis model menjadi tidak jelas; gunakan panduan error token autentikasi Claude Code ketika autentikasi juga gagal.
Langkah 5: Putuskan apakah akan retry, fallback, atau fail closed
Jangan retry error deterministic missing-model tanpa batas. Gunakan kebijakan ini:
| Pola error | Retry? | Fallback? | Tindakan manusia |
|---|---|---|---|
| Typo atau model ID usang | Tidak | Hanya setelah konfigurasi diperbaiki | Perbarui registry model dan deploy ulang |
| Alias baru belum ada di router | Tidak ada retry berulang | Pertahankan model terverifikasi sebelumnya | Buka tugas enablement/canary route |
| Workspace tidak punya akses | Tidak | Mungkin, jika ada fallback yang disetujui | Perbaiki key, workspace, atau allowlist |
| 400 request-shape mismatch | Tidak | Belum sampai request diperbaiki | Patch body request atau feature flag |
| 529 overloaded atau outage upstream sementara | Ya, backoff terbatas | Ya, jika kebijakan fallback mengizinkan | Monitor kesehatan route |
Untuk penanganan overload sementara, gunakan runbook yang berbeda: API Error 529 overloaded. Kegagalan versi model biasanya bersifat deterministik sampai Anda mengubah konfigurasi.
Checklist review route Flatkey
Saat Claude menjadi bagian dari sistem multi-model, router memberi Anda satu tempat untuk meninjau nama model, key, allowlist, biaya, dan fallback. Posisi Flatkey adalah satu key, satu saldo, satu invoice, endpoint model resmi, dan usage ledger bersama lintas model dan tools.
Gunakan checklist ini sebelum mempromosikan route Claude baru:
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
Untuk desain route yang lebih luas, baca Claude API proxy vs multi-model router dan panduan katalog model AI. Untuk tradeoff biaya dan routing, padukan artikel ini dengan harga Claude API dan LLM API fallback routing.
Checklist insiden yang bisa disalin
Gunakan ini di Slack, Linear, GitHub, atau dokumen insiden Anda:
## Insiden model Claude version not found
- String model yang gagal:
- Surface API: Anthropic native / router / Bedrock / Vertex / lainnya
- Base URL:
- Path request:
- SDK atau client:
- Kode status:
- error.type:
- request-id:
- Deploy pertama yang gagal:
- Alias model resmi saat ini yang diperiksa:
- Apakah permintaan minimal lolos?
- Apakah model diaktifkan untuk workspace/key/sub-key ini?
- Apakah ini error fitur tidak didukung, bukan model-not-found?
- Model rollback:
- Owner:
Jaga checklist tetap membosankan. Tujuannya adalah mencegah versi model Claude yang hilang berubah menjadi insiden luas di mana setiap tim mengubah pengaturan yang berbeda.
Pertanyaan yang sering diajukan
Apakah "Claude model version not found" sama dengan 404?
Sering kali, tetapi tidak selalu. Anthropic mendokumentasikan 404 - not_found_error untuk resource yang hilang, sementara SDK dan gateway mungkin merumuskan ulang pesannya. Pertahankan status code mentah dan error.type sebelum memutuskan.
Versi model Claude mana yang sebaiknya saya gunakan?
Gunakan alias model terkini dari API atau surface provider yang Anda panggil. Jangan menyalin versi model Claude dari cloud provider lain, router, atau contoh kode lama tanpa memeriksa katalog endpoint tersebut.
Haruskah saya menggunakan alias atau snapshot bertanggal?
Untuk sebagian besar tim aplikasi, alias terkini lebih mudah dioperasikan karena provider mengontrol pemetaan yang didukung. Jika Anda membutuhkan reproduktibilitas yang ketat, dokumentasikan kebijakan snapshot yang tepat, rencana pensiun, dan jalur rollback.
Bisakah Flatkey memperbaiki Claude model version not found secara otomatis?
Flatkey tidak dapat membuat ID model upstream yang tidak valid menjadi valid, tetapi dapat mengurangi tempat-tempat di mana ID yang salah tersembunyi. Gunakan Flatkey untuk memusatkan review katalog model, routing satu kunci, allowlist sub-kunci, log penggunaan, dan kebijakan fallback ketika Claude hanya satu route model di antara banyak route.
Kapan saya harus fallback ke model lain?
Fallback sesuai setelah Anda mengklasifikasikan kegagalannya. Jangan fallback jika penyebabnya typo, base URL yang salah, atau key yang tidak berwenang. Lakukan fallback ketika kebijakan Anda menyatakan route saat ini tidak tersedia dan route berikutnya telah lolos pemeriksaan input, kualitas, dan biaya yang sama.
Pemeriksaan akhir
Sebelum Anda menutup tiket claude model version not found, konfirmasi perbaikannya di tiga tempat: konfigurasi sumber, smoke test API minimal, dan log route produksi. Kemudian tambahkan versi model Claude yang berfungsi ke model registry Anda agar deployment berikutnya tidak memperkenalkan kembali string usang yang sama.
Jika Anda sudah merutekan beberapa model, uji perubahan yang sama melalui Flatkey sehingga request ledger, kebijakan fallback, dan allowlist model semuanya selaras sebelum traffic produksi berpindah.
