API 401 veya 404 hatası: yanlış anahtar, temel URL veya model kimliği

İsteğiniz bir durum koduyla başarısız oldu ve önce neye dokunacağınızdan emin değilsiniz. Kısa cevap: 401 genellikle anahtara işaret eder, 404 genellikle yanlış kapıyı çaldığınız anlamına gelir — ya adres (temel URL ve yol) ya da model kimliği. Bu sırayla kontrol edilecek üç şey ve düzeltmeyi kanıtlayan bir curl komutu.

OpenAI'nin hata kodları sayfası (26 Ekim 2026'da kontrol edildi) iki 401 mesajı listeler: "Invalid Authentication" ve "Incorrect API key provided". Her ikisi için verdiği çözüm aynıdır: anahtarı kontrol edin veya yeni bir tane oluşturun. Sayfa, API'nin kendisi için hiçbir 404 belgelemez, bu nedenle 404 için aşağıdaki kural o sayfadan değil, OpenAI uyumlu uç noktaların nasıl çalıştığından gelir.

Aralarındaki farkı söylemenin hızlı yolu#

Mesajın ifadesi sunucuya ve aracınıza bağlıdır (Cline, Aider, OpenCode ve Continue hataları kendi yöntemleriyle sarar), bu nedenle numaradan başlayın, ardından aşağıdaki curl kontrolüyle doğrulayın.

401: anahtar uç noktayla eşleşmiyor#

Klasik hikaye: bir aracı yeni bir sağlayıcıya taşıdınız, temel URL'yi değiştirdiniz ve eski sağlayıcının anahtarını yapılandırmada bıraktınız. Adres yeni, anahtar eski ve sunucu 401 yanıtı veriyor. Hiçbir şey bozuk değil; anahtar sadece farklı bir eve ait.

Kontrol edilecekler:

1. Anahtarı hangi sağlayıcı verdi? Aradığınız adresin sahibi o olmalı. Bir hizmet için alınan anahtar diğerinde geçerli değildir.
2. Başıboş karakterler. Anahtarla birlikte yapıştırılan bir boşluk veya satır sonu ya da değerin içine kaçan tırnak işaretleri.
3. Aracın anahtarı nereden okuduğu. Bir terminalde ayarlanmış ama düzenleyicinizin başlattığı terminalde ayarlanmamış bir ortam değişkeni sık görülen bir nedendir. Aracın hem yapılandırma dosyası hem de ortam değişkeni varsa hangisinin kazandığını öğrenin.
4. İptal edilmiş veya silinmiş bir anahtar. Sildiğiniz veya iptal ettiğiniz anahtar çalışmayı durdurur — yeni bir tane oluşturun ve yapılandırmaya koyun.

Anahtarların nasıl çalıştığından veya nerede saklanacağından emin değilseniz, API anahtarı nedir ve güvenle nasıl saklanır bunu sade bir dille anlatır.

Her modelde 404: adres yanlış#

CheapTokens için temel URL https://api.cheaptokens.dev/v1. Araçlar ve SDK'lar uç nokta yolunu kendileri ekler, bu nedenle olağan hatalar /v1 ile ilgilidir:

• Eksik /v1: araç sonunda https://api.cheaptokens.dev/chat/completions çağırır.
• İkili /v1: tam yolu zaten ekleyen bir alana yapıştırdınız ve https://api.cheaptokens.dev/v1/v1/chat/completions elde edersiniz.
• Yanlış tür: OpenAI tarzı araçlar ve OpenAI SDK'sı adresi /v1 ile alır. Anthropic SDK'sı ve Claude Code adresi /v1 olmadan alır: https://api.cheaptokens.dev.

Temel URL'nin tam olarak ne olduğunu ve aracın hangi kısmı eklediğini hiç merak ettiyseniz, bu açıklama bunu adım adım anlatır. Anthropic tarafı için CheapTokens ile Anthropic Python SDK'sı sayfasına bakın.

Bir modelde 404: model kimliği#

Bu, bir fiyat tablosundan veya başka bir sağlayıcıdan ad kopyalayanları yakalar. Bir fiyat tablosu DeepSeek-V4-Flash diyebilir; API, geliştirici öneki ve sürümle birlikte tam ağ geçidi kimliğini ister:

Fiyat etiketlerindeki kısa kimlikler API tarafından kabul edilmez ve yazım önemlidir: büyük harfler, eğik çizgi, -0731 son eki. Kimliği ezberden yazmak yerine CheapTokens belgelerinden kopyalayın — farklı sağlayıcılar aynı modeli farklı adlandırır. Anahtarınız için mevcut tam kimlikleri görmek üzere aynı Authorization başlığıyla GET https://api.cheaptokens.dev/v1/models çağırın ve kimliği listeden kopyalayın:

curl https://api.cheaptokens.dev/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Tablodaki ad mantığı tuhaf görünüyorsa, AI model adları nasıl okunur takma ad ile sabitlenmiş sürüm arasındaki farkı açıklar.

Düzeltmeyi tek bir curl komutuyla kanıtlayın#

Aracı devre dışı bırakın ve API'yi doğrudan çağırın. Anahtar yer tutucusunu kendi anahtarınızla değiştirin:

curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [{"role": "user", "content": "Say hi in one word."}],
    "max_tokens": 20
  }'

Bu tek istekte üç şüphelinin hepsi vardır: başlıktaki anahtar, ilk satırdaki temel URL, gövdedeki model kimliği. choices dizisi içeren bir JSON yanıtı, üçünün de doğru olduğu anlamına gelir ve aracınızın farklı yaptığı şey sorundur. Başarısız olursa, her seferinde bir şeyi değiştirin:

• 401 → CheapTokens'ten aldığınız anahtarı koyun ve tekrar çalıştırın.
• 404 → URL'yi yukarıdakiyle karakter karakter karşılaştırın, ardından model kimliğini.

curl çalıştıktan sonra aynı üç değeri araca kopyalayın: anahtar, temel URL (https://api.cheaptokens.dev/v1 veya Anthropic SDK'sı ve Claude Code için /v1 olmadan) ve tam model kimliği.

Hâlâ çalışmıyorsa#

• Araçta aynı hata, curl sorunsuz. Araç başka bir yerden eski bir anahtar veya URL okuyor: ikinci bir yapılandırma dosyası, kayıtlı bir profil, bir ortam değişkeni. Değiştirdikten sonra aracı yeniden başlatın.
• Model kimliğinin doğru olduğundan emin değilseniz. Anahtarınızla GET /v1/models çağırın ve kimliği listeden kopyalayın.
• Bağlantı reddedildi, zaman aşımları, sertifika hataları. Bu bir 401 veya 404 değildir; yaygın bağlantı hataları sayfasına bakın.
• İlk isteğin nasıl görünmesi gerektiğinden emin değilseniz. İlk API isteğiniz adım adım anlatır ve belgeler tam referansı içerir.

Korunmaya değer alışkanlık: bir çağrı başarısız olduğunda önce numarayı okuyun. 401 genellikle anahtar, 404 genellikle adres veya model kimliği anlamına gelir ve curl bunu kesinleştirir. Bu, tek bir günlük açmadan önce bu hataların çoğunu çözer.