ANTHROPIC_BASE_URL 404 hatası: tek bir yol parçası

Claude Code, bir SDK veya bir curl çağrısı özel bir uca karşı 404 page not found döndürüyorsa, sebep neredeyse her zaman tek bir yol parçasıdır. Anthropic biçimli istemciler base URL’de `/v1` istemez; OpenAI biçimliler ister. Tek anahtar, tek host, iki farklı dize — ve yanlış olan 404 verir, ki çoğu istemci bunu yanlış yol değil bağlantı sorunu diye raporlar.

Ölçümler ne gösteriyor

2026-08-30’de bu istasyonun ucuna karşı çalıştırıldı; yalnızca yol ve kimlik başlığı değişiyor:

Üçüncü satır yazının tamamı. /v1/v1/messages, /v1’i kendisi ekleyen bir istemcinin base URL’sine /v1 koyduğunuzda ortaya çıkar. İki yarı da tek başına doğru olduğu için yapması kolay, görmesi zordur.

İlk iki satır ayrıca bilmeye değer: Anthropic biçimli bir yolda iki kimlik yöntemi de çalışıyor. 404 değil de 401 ayıklıyorsanız sorununuz başlık değil.

Neden bağlantı hatası gibi görünüyor

Var olmayan bir yoldan gelen 404’ü genellikle model değil ağ geçidi döndürür, dolayısıyla gövde istemcinin beklediği JSON hata biçimi yerine düz metin veya HTML olur. İstemci ayrıştıramaz ve size ulaşan şey “bağlanılamadı”, “API Error” ya da JSON ayrıştırıcısından gelen bir yığın izi olur.

Yani belirti ağı işaret ediyor, sebep ise ayar dosyanızdaki bir dize. Bir istek uca ulaşabiliyorsa — reddedilmek için bile olsa — ağ sağlamdır.

Ayırmanın hızlı yolu: base URL’yi tek başına curl -sv ile çağırın. Tamamlanan bir TLS el sıkışması DNS, güvenlik duvarı ve sertifika sorunlarını tek adımda eler ve geriye bir yönlendirme sorusu bırakır.

İkinci sebep: abonelik ve base URL aynı anda

Aynı 404’ü üreten ve yollarla hiç ilgisi olmayan ayrı bir arıza var. Claude Code’da Pro veya Max planından gelen OAuth kimliği varken ortamınızda veya settings.json dosyanızda ANTHROPIC_BASE_URL da tanımlıysa, özel URL sessizce kazanır — yani abonelik kimliği taşıyan istekler, o kimliği hiç duymamış bir uca gider.

Sonuç, anlamsız görünen bir 404 veya “model bulunamadı” olur; çünkü model, çağırdığınızı sandığınız uçta gerçekten var.

• Aboneliği mi istiyorsunuz? ANTHROPIC_BASE_URL’i ortamdan ve ~/.claude/settings.json’dan kaldırın, sonra /logout yapıp yeniden girin.
• Özel ucu mu istiyorsunuz? Değişkeni bırakın ve ANTHROPIC_AUTH_TOKEN’ı o ucun anahtarına ayarlayın; böylece istek, ucun beklediği kimliği taşır.
• Hangisi aktif emin değil misiniz? env | grep ANTHROPIC çalıştırın ve ~/.claude/settings.json’ı okuyun. İki kaynak var ve unutulan hep dosya oluyor.

Üçüncü sebep: doğru yol, yanlış API

Bazı parametreler bir uçta var, diğerinde yok; yanlış yerde istemek 404 değil 400 üretir — ama aynı ayıklama oturumuna denk geldiği için burada anmaya değer.

Aynı uçta ölçüldü: /v1/chat/completions’a gönderilen tools: [{"type":"web_search"}] bazı modellerde Unknown parameter: tools[0].function döndürüyor, bazılarında ise sessizce yok sayılıyor — HTTP 200, araç çağrısı yok, atıf yok. Aynı istek /v1/responses’ta çalışıyor. Katı JSON şeması da aynı davranıyor: chat completions’ta response_format, bir Responses-API alanının adını veren bir hatayla düşüyor.

Bir özellik “çalışmıyor” ama 200 dönüyorsa, modeli kontrol etmeden önce ucu kontrol edin.

Dördüncü sebep: istediğiniz şey olmayan bir 200

Yol düzeldikten sonra bile istemcinizi kıran bir yanıt alabilirsiniz ve olmayan bir 404’ü aramaya başlamadan önce bunun biçimini bilmek işe yarar.

Bazı modeller, akış istemediğiniz düz bir isteğe yine de sunucu gönderimli olaylarla cevap veriyor. 2026-08-30’de ölçüldü: bir model, istekte hiç stream: true olmadan beş denemenin beşinde data: {"object":"chat.completion.chunk"} döndürdü. Akışsız create() çağıran bir SDK, tamamlama yerine JSON ayrıştırma hatası alır — gövde JSON değildir, yani hata ayrıştırıcıdan gelir ve bozuk bir uçtan gelen hatalı yanıt gibi görünür.

Kontrol yeniden deneme değil, bir başlık: ayrıştırmadan önce içerik tipini okuyun. text/event-stream görüyorsanız, ne istemiş olursanız olun akış olarak okuyun.

Sorunu bitiren kontrol listesi

1. 01`/v1`’leri sayın. Base URL’nizdeki ile istemcinin eklediğini toplayın. Toplamda tam olarak bir tane.
2. 02Tam yolu doğrudan curl ile çağırın. İstemciyi tek komutla denklemden çıkarır.
3. 03Çakışan bir kimlik var mı bakın. OAuth artı özel base URL, sessiz olan durum.
4. 04Ucun modeli sunduğunu doğrulayın. GET /v1/models anahtarınızın gerçekten erişebildiklerini listeler; gönderdiğiniz kimlikle karşılaştırın.
5. 05API ailesini kontrol edin. Web arama ve katı JSON /v1/responses’ta, chat completions’ta değil.
6. 06Zaman aşımını cömert tutun. Yol düzeldikten sonra bazı modeller akışsız çok daha uzun sürer; kısa zaman aşımı yeni bir arıza gibi görünür.

Altı kontrol, ve çoğu zaman ilk ikisi meseleyi bitiriyor.

Devamı

• “OpenAI uyumlu” gerçekte ne demek — uyumlu bir ucun sessizce uyumlu olmadığı diğer yerler.
• AI API relay’leri, açıklandı — özel bir base URL’nin arkasında ne var ve nasıl denetlenir.
• İstemciniz yeniden denerken erişilebilirlik ne demek — yol düzeldikten sonra hata gibi görünen ama olmayan bir sonraki şey.

Yukarıdaki her komut bizim ucumuzda yazıldığı gibi çalışıyor; kurulum sayfasında araç başına aynı iki base URL ve yanlarında birer doğrulama komutu var, durum sayfasında da şu an hangi modellerin cevap verdiği duruyor.