1. Kodda kullanılan model adını birebir kontrol edin
Önce hatayı karmaşıklaştırmadan model parametresine bakın. Çoğu sorun tek satırdan çıkar. Model adı eksik, eski, kopyalanırken bozulmuş veya görünür ürün adı olarak yazılmış olabilir.
Kontrol edilmesi gereken örnek alan:
model="claude-sonnet-4-5"
veya: (JavaScript Kod)
model: "claude-sonnet-4-5"
Şunlara dikkat edin:
Model adı boşluk içeriyor mu?
Büyük harf kullanılmış mı?
Tireler doğru mu?
Eski model ID’si mi kullanılıyor?
Webde görünen pazarlama adı API ID’si sanılmış mı?
.env içinde farklı model adı mı duruyor?
Kodda model adı birden fazla yerde mi tanımlı?
Özellikle .env, config dosyası, Docker environment, serverless secret ve frontend/backend ayrımını kontrol edin. Bazen kodu düzeltirsiniz ama canlı ortam hâlâ eski model adını kullanır.
2. Güncel model listesini resmî Models API ile doğrulayın
En temiz çözüm, model adını tahmin etmek yerine Anthropic’in model listeleme endpoint’inden mevcut modelleri kontrol etmektir. Anthropic’in resmî dokümantasyonunda Models API response çıktısının API’de kullanılabilir modelleri belirlemek için kullanılabileceği ve daha yeni modellerin önce listelendiği belirtilir.
Mantık basittir: Eğer kullanmak istediğiniz model bu listede yoksa, yanlış platformdasınız, erişiminiz yoktur ya da model adı artık geçerli değildir.
Uygulanacak kontrol:
curl https://api.anthropic.com/v1/models \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"
Dönen listede model ID’sini birebir kopyalayın. Görünen açıklama adını değil, API’nin verdiği id alanını kullanın.
3. Eski veya emekli model adlarını güncelleyin
Claude modelleri zaman içinde yenilenir. Eski model adları bir süre çalışabilir, sonra legacy/deprecated/retired aşamasına geçebilir. Emekli olmuş modellerde istekler başarısız olur.
Kodda eski bir model adı varsa:
Güncel model listesine bakın.
Eski modeli aktif önerilen modelle değiştirin.
Test ortamında çıktı kalitesini kontrol edin.
Üretim ortamına geçmeden önce maliyet, hız ve kalite farkını ölçün.
Dokümantasyondaki migration notlarını inceleyin.
Özellikle eski projelerde model adı environment variable içinde unutulur. Kod güncel görünse bile canlı sunucu hâlâ eski modelle istek atıyor olabilir.
4. Anthropic API, Bedrock ve Vertex AI model adlarını karıştırmayın
Claude’u farklı platformlardan kullanabilirsiniz; fakat her platform model adını aynı şekilde istemeyebilir. Anthropic API’de çalışan bir model ID’si, Amazon Bedrock’ta farklı format isteyebilir. Bedrock model ID’si de doğrudan Anthropic API’de çalışmayabilir.
Ayırmanız gerekenler:
5. OpenAI SDK compatibility kullanıyorsanız base URL ve model adını birlikte kontrol edin
Bazı geliştiriciler OpenAI SDK ile Claude API’ye bağlanır. Bu yapı çalışabilir; ancak base URL, API key ve model adı birlikte doğru olmalıdır. Sadece API key’i değiştirmek yetmez.
Kontrol edin:
client = OpenAI(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
base_url="https://api.anthropic.com/v1/"
)
Sonra model alanında Claude model ID’si kullanılmalıdır:
model="claude-sonnet-4-5"
Burada sık yapılan hata, OpenAI model adını Claude endpoint’ine göndermek veya Claude model adını OpenAI endpoint’ine göndermektir. İkisi de geçersiz model hatasına neden olur.
6. Model adını tek bir config değişkeninden yönetin
Büyük projelerde model adı bazen backend, worker, cron job, queue processor, test dosyası ve frontend config içinde ayrı ayrı yazılır. Birini güncelleyip diğerini unutursanız hata aralıklı görünür.
Daha sağlıklı yapı:
CLAUDE_MODEL=claude-sonnet-4-5
Uygulama içinde sadece bu değişken okunur. Böylece model değişikliği tek yerden yapılır. Ayrıca deploy loglarında kullanılan model adını maskelemeden ama net şekilde görmek iyi olur.
Örnek log:
Claude model selected: claude-sonnet-4-5
Bu sayede hata olduğunda gerçekten hangi modelin çağrıldığını anlarsınız.
7. Yanlış model adını kullanıcı ayarlarından geliyorsa doğrulama ekleyin
Bazı uygulamalarda kullanıcı model seçebiliyor. Eğer kullanıcı serbest metin olarak model adı giriyorsa geçersiz model hatası kaçınılmaz hale gelir. Bunun yerine model seçimi güvenli bir liste üzerinden yapılmalıdır.
İyi yaklaşım:
Model adını serbest yazdırmayın.
Dropdown veya sabit seçenek kullanın.
Sunucu tarafında izinli model listesi tutun.
Kullanıcının seçtiği model API’ye gitmeden önce doğrulansın.
Geçersizse daha anlaşılır hata verin.
8. API hata tipini doğru okuyun
Her model hatası aynı değildir. not_found_error, modelin bulunamadığını veya kaynağın erişilebilir olmadığını düşündürür. permission_error, model var ama hesabın erişimi yok anlamına gelebilir. invalid_request_error ise istek formatında veya model alanında hata olabileceğini gösterir.
Kabaca şöyle okuyabilirsiniz:
not_found_error: Model ID yanlış, emekli, erişilemeyen kaynak veya yanlış endpoint.
invalid_request_error: İstek formatı, model alanı veya parametre hatası.
permission_error: Model veya kaynak için yetki yok.
authentication_error: API key yanlış veya eksik.
rate_limit_error: Model adı doğru olabilir ama kullanım sınırına takıldınız.
Bu ayrım önemlidir. Çünkü model adı yanlışsa API key yenilemek işe yaramaz. Yetki sorunu varsa model adını değiştirmek yerine hesap erişimi kontrol edilmelidir.
9. Deploy ortamında eski environment variable kalmadığını kontrol edin
Yerel bilgisayarda kod çalışır ama sunucuda hata verirse en sık neden canlı ortamın eski değişkenleri kullanmasıdır. Özellikle Vercel, Render, Docker, Kubernetes, PM2, systemd veya CI/CD ortamlarında bu çok görülür.
Kontrol edin:
.env dosyası güncel mi?
Production environment variable güncellendi mi?
Docker container yeniden build edildi mi?
Serverless ortam yeniden deploy edildi mi?
Worker process restart edildi mi?
Secret manager eski değeri tutuyor mu?
Cache veya config snapshot yenilendi mi?
Model adı değişikliği yaptıktan sonra sadece kodu commit etmek yetmeyebilir. Çalışan servis eski environment ile devam ediyorsa hata sürer.
10. Geçici çözüm olarak güvenilir aktif modele dönün
Canlı sistemde kullanıcılar hata alıyorsa önce sistemi ayağa kaldırmak gerekir. En hızlı çözüm, güncel model listesinden doğruladığınız aktif ve erişilebilir bir Claude modeline dönmektir.
Güvenli yaklaşım:
Güncel model listesini çekin.
Erişilebilir model ID’sini seçin.
Config değerini güncelleyin.
Servisi yeniden başlatın.
Küçük test isteği gönderin.
Loglarda model adını doğrulayın.
Sonra kalıcı migration planını yapın.
Rastgele eski model adlarına dönmeyin. Çalışan, listede görünen ve hesabınızın erişebildiği model ID’sini kullanın.
