API hataları: nedenleri ve çözümleri
Her makale doğrudan cevapla başlar ve sebebi kendiniz doğrulayabileceğiniz bir komut verir. Hata mesajları, terminalinizde göründüğü gibi orijinal İngilizce halleriyle yazılmıştır.
OpenAI uyumlu bir API'yi çağırırken Unexpected token '<' hatasıİstemciniz JSON beklerken HTML aldı. Neredeyse her zaman base URL'de /v1 eksiktir ya da iki kez yazılmıştır. Tek komutla nasıl doğrulanır ve nasıl düzeltilir.401 invalid API key – anahtar doğru göründüğü halde hata veriyorsaAz önce kopyaladığınız bir anahtarla gelen 401 genellikle boşluk karakterine, yanlış başlığa ya da erişemediği modellere bağlı bir anahtara dayanır. Hangisi olduğunu nasıl anlarsınız.Uç nokta açıkça var olduğu halde /v1/chat/completions için 404Çalıştığını bildiğiniz bir uç noktadan 404 almak neredeyse her zaman API'nin POST beklediği yerde GET kullanmaktır ya da bir segment kaymış yoldur. İkisini nasıl ayırt edersiniz.Uzun API isteklerinde 524 zaman aşımı524, modelden değil API'nin önündeki bir CDN'den gelir. Kaynak sunucu çok uzun süre hiçbir şey göndermediğinde tetiklenir – stream'li isteklerin hayatta kalıp stream'siz olanların kalmamasının sebebi budur.Model not found – model adı neredeyse doğru olduğundaBu hata neredeyse her zaman model adının tam olarak eşleşmediği ya da anahtarınızın ona erişim kapsamında olmadığı anlamına gelir. Gerçekte neleri çağırabildiğinizi nasıl listelersiniz.Bir API ağ geçidinden gelen 429 iki farklı anlama gelirBir ağ geçidi hem bakiyeniz bittiğinde hem de üst sağlayıcı yoğun olduğunda 429 döndürür. Biri yeniden denemeye değer, diğeri asla değmez. Yanıt gövdesinden ikisini nasıl ayırt edersiniz.Tarayıcıdan bir yapay zekâ API'sini çağırırken CORS hatasıCORS hatası belirtidir. Asıl sorun, tarayıcıdan yapılan bir isteğin API anahtarınızı her ziyaretçiye taşımasıdır. Bunun yerine ne yapmalı ve neden hiçbir başlık ayarı bunu çözmez.Bir reasoning modelinde araç çağrısını zorlarken 400tool_choice'u any ya da tool olarak ayarlamak, yanıt vermeden önce her zaman düşünen modeller tarafından reddedilir. Bunun yerine ne göndermeli ve bu modellerin reddettiği diğer parametreler.Cloudflare arkasında istekler tam 100 saniyede kesiliyorUzun bir completion, neredeyse tam 100 saniyede 524 ya da kopan bir stream ile başarısız oluyor. Bu sayı sizin sunucunuzun değil, Cloudflare proxy'sinin sınırıdır. Nasıl doğrulanır ve aşmanın üç yolu.Model boş bir dize döndürüyor ama yine de ücret alınıyorYanıt HTTP 200 ile geliyor, content boş bir dize ve kullanım kaydında çıktı token'ları ücretlendirilmiş. Reasoning modellerinde bu neredeyse her zaman max_tokens'ın görünür metin üretilmeden tükenmesidir.Stream'li bir yanıt cümlenin ortasında duruyorToken'lar gelir, sonra durur ve hiçbir hata oluşmaz. Tamamlanmış bir stream ile kopmuş bir stream arasındaki fark SSE gövdesindeki tek bir satırdır – ve çoğu istemci kodu bunu hiç kontrol etmez.Dün çalışan bir model artık aynı anahtar grubundaki herkes için hata veriyorÇalışan bir model, bir gruptaki her anahtar için hata vermeye başlıyor, diğer gruplar etkilenmiyor. Bu model değil yönlendirmedir: Tek bir bozuk üst hesap koca bir grubu çökertebilir.Fatura, token sayısının haklı çıkaracağından yüksekKaydedilen token toplamları mütevazı görünüyor ama ücret öyle değil. Claude ailesi modellerde genel sebep önbellek yönüdür: önbelleğe yazmak normal girdiden pahalı, okumak ise onun küçük bir kesridir ve aynı token'lar on iki kata kadar farklı fiyatlanabilir.Claude Code ve Codex aynı ağ geçidinde farklı base URL'ler isterAynı ağ geçidi, aynı anahtar, iki kodlama ajanı – ve birinde çalışan base URL diğerinde başarısız oluyor. Hangi istemcinin yolu kendisinin eklediğini bildiğinizde kural basittir.Bir yapay zekâ API'sini çağırırken 405 Method Not AllowedBir yapay zekâ uç noktasındaki 405 neredeyse hiçbir zaman yöntemin yanlış olduğu anlamına gelmez. POST'un yalnızca sayfa sunan bir yere düştüğü anlamına gelir – genellikle çıplak alan adına, çünkü base URL'de /v1 eksiktir. Tek komutla nasıl doğrulanır./responses için 404 – Responses API de sürüm ön ekine ihtiyaç duyarchat/completions'tan Responses API'ye geçen istemciler sık sık sürüm ön ekini düşürür. 404, herhangi bir API kodu çalışmadan önce uç katmandan gelir, bu yüzden çağrı kullanım kaydınızda hiç görünmez.context_length_exceeded – sınıra gerçekte neler sayılırSınır yalnızca son mesajınızı değil, tüm konuşmayı ve cevap için ayrılan alanı kapsar. İstemi kısaltmanın neden çoğu zaman işe yaramadığı ve bunun yerine neyi kesmeniz gerektiği.Claude'dan 529 overloaded_error – nedir ve ne yapmalı529, üst sağlayıcının şu anda doymuş olduğu anlamına gelir. Bir kota sorunu değildir ve anahtarınızın çözebileceği bir şey değildir. 429'dan nasıl ayırt edilir ve gerçekten işe yarayan yeniden deneme kalıbı.Kesinlikle doğru bir anahtarla 401 – başlık formatını kontrol edinBir anahtar tamamen geçerli olup yine de başlık yanlış oluşturulduğu için 401'e yol açabilir. Bunun ters gittiği üç yol ve istemcinizin gerçekte gönderdiği başlığı nasıl görürsünüz.Bir reasoning modelinde 400 unsupported parameterReasoning modelleri, diğer tüm modellerin kabul ettiği örnekleme parametrelerini reddeder. Hangilerini kaldırmalı, varsayılanın neden zaten istediğiniz şey olduğu ve iki model türü için tek bir kod yolunu nasıl korursunuz.Stream'li bir yanıtta token kullanımı eksikStream'li bir yanıt, siz istemedikçe token sayılarını taşımaz. Nasıl açılır, son parça nerede gelir ve bir ağ geçidi göndermiyorsa ne yapmalı.Araç çağrısında 400 – her tool_use eşleşen bir tool_result isterHata, yapılan yanlıştan bir tur sonra ortaya çıkar ve kafa karıştıran da budur. Eşleştirme kuralı, sıralama kuralı ve bir kez düzeltebilmek için hatayı kasıtlı olarak nasıl yeniden üretirsiniz.JSON modu yine de ayrıştırılamayan metin döndürüyorresponse_format biçimi sınırlar, bitişi değil. Kesilme, eksik şema zorlaması ve nesnenin etrafındaki düz yazı, ayrıştırmayı her biri farklı bir şekilde bozar.Çağrı curl ile çalışıyor ama uygulamanızdan çalışmıyorAynı anahtar, aynı URL, farklı sonuç. Fark neredeyse her zaman curl'ün yapmadığı bir şeydedir: bir proxy, eskimiş bir ortam değişkeni, bir IP kısıtlaması ya da isteğinizi yeniden yazan bir kütüphane.Bir yapay zekâ API'sini çağırırken SSL certificate verify failedcurl çalışırken SDK'nızdan gelen bir TLS hatası neredeyse her zaman trafiği yeniden imzalayan bir kurumsal proxy ya da antivirüstür. Doğrulamayı kapatmanın neden yanlış çözüm olduğu ve doğru olan üç çözüm.Stream'li bir yanıtın ortasında socket hang upYarıda duran bir stream size eksik bir cevap bırakır ve modelden hiçbir hata gelmez. Bir ağ kopmasını üst taraftaki bir iptalden nasıl ayırırsınız ve her biri için ne yapmalı.Claude Code: API Error 400 prompt is too longHata isteği adlandırır ama sebep birikmiş oturum bağlamıdır: okunan dosyalar, araç çıktıları ve konuşma geçmişi her turda yeniden gönderilir. Neyi temizlemeli, neyi tutmalı.Görsel girdi bir vision modeli tarafından reddediliyorVision uç noktaları görselleri, neredeyse aynı hataları üreten dört farklı sebeple reddeder. Yeniden kodlamaya başlamadan önce bunları nasıl ayırt edersiniz.Sistem istemi modeller arasında farklı davranıyorBaskın iki API biçimi sistem talimatlarını farklı yerlere koyar. Biri için yazılan kod diğerinde hata vermek yerine sessizce kötüleşir; bu da bir hatadan daha kötüdür.Bir 429'u doğru okumak – Retry-After ve sınır başlıklarıYeniden deneme kodlarının çoğu tahmin yürütür. Yanıt genellikle ne kadar beklemeniz gerektiğini ve hangi sınıra takıldığınızı tam olarak söyler. Nasıl okunur ve başlık yoksa ne yapmalı.Özel bir uç noktanın modelleri istemcinin listesinde görünmüyorMasaüstü istemcileri model listelerini farklı şekillerde oluşturur ve birkaçı /v1/models'i hiç çağırmaz. Hangi türe sahip olduğunuzu nasıl anlarsınız ve her durumda ne yapmalı.finish_reason content_filter ile boş yanıtcontent_filter bitiş sebebiyle gelen boş bir completion, bir güvenlik sisteminin onu durdurduğu anlamına gelir. Bunu kesilmeden ve gerçek bir hatadan nasıl ayırırsınız ve size maliyeti ne olur.Kullanım kaydındaki zaman damgaları çağrıyı yaptığınız zamanla uyuşmuyorYaptığınız andan saatlerce uzakta görünen bir çağrı, neredeyse her zaman kaybolmuş bir kayıt değil, bir saat dilimi farkıdır. Bir faturalama sorunu bildirmeden önce ikisini nasıl hizalarsınız.Tek istek gibi görünen bir şey için iki kez ücretlendirildimİstemci tarafındaki bir zaman aşımı, sunucuda zaten çalışan işi durdurmaz. Kazara çift ücretlendirmenin olağan şekli ve bunu önleyen iki değişiklik.