CometAPI hata yönetimi, istek yapısı sorunlarını, kimlik doğrulama sorunlarını, yol hatalarını ve yeniden denenebilir platform hatalarını birbirinden ayırdığınızda en kolay hale gelir. İsteği düzeltmeniz mi yoksa yeniden denemeniz mi gerektiğine karar vermek için HTTP status, error.code ve error.message birleşimini kullanın.
Hızlı değerlendirme
Hata zarfı
Birçok CometAPI hatası bunun gibi bir hata gövdesi kullanır:
Bazı yanıtlar code alanını boş bırakır. Status 500 olduğunda, belirleyici sinyal olarak error.code ve error.message alanlarını değerlendirin.
400 Bad Request
Bir 400 genellikle istek normal şekilde işlenmeden önce istek gövdesinin doğrulamadan geçemediği anlamına gelir.
Yaygın nedenler:
model gibi zorunlu alanların eksik olması- Geçersiz JSON yapısı
- Yanlış türde bir alan gönderilmesi
- Seçilen endpoint’in kabul etmediği sağlayıcıya özgü parametrelerin yeniden kullanılması
Bilinen şekilde çalışan en basit istekten başlayın, ardından isteğe bağlı alanları tek tek geri ekleyin. Yükü API referansındaki endpoint şemasıyla karşılaştırın.
Bunun gibi minimal bir istek kullanın:
your-model-id değerini CometAPI Models page üzerindeki güncel bir model ID ile değiştirin.
Hatalı biçimlendirilmiş her chat isteğinin 400 döndüreceğini varsaymayın. messages gibi zorunlu chat alanlarının eksik olması, error.code: invalid_request ile birlikte 500 olarak da ortaya çıkabilir.
500 Internal Server Error
Çoğu 500 yanıtı bir platform veya sağlayıcı hatasına işaret eder. Chat Completions için bazı hatalı biçimlendirilmiş istekler de 500 olarak görünebilir ve yine de error.code: invalid_request taşıyabilir.
Buna bir örnek, messages alanını içermeyen bir istektir:
Bir 500 yanıtı error.code: invalid_request içeriyorsa, bunu bir istek sorunu olarak değerlendirin:
- İstek gövdesini düzeltin.
- Yükü endpoint şemasıyla karşılaştırın.
- Yalnızca yükü düzelttikten sonra yeniden deneyin.
Bir 500 yanıtı geçersiz bir isteğe işaret etmiyorsa, request id değerini saklayın ve backoff kullanın.
401 Invalid Token
Bir token hatası genellikle şöyle görünür:
Kontrol edilmesi gerekenler:
- Header tam olarak
Authorization: Bearer $COMETAPI_KEY olmalıdır.
- Uygulamanızın
.env, shell geçmişi veya dağıtılmış bir secret store içinden eski bir anahtar yüklemediğinden emin olun.
- Aynı istekte bir anahtar başarısız olurken başka bir anahtar çalışıyorsa, bunu endpoint sorunu değil token sorunu olarak değerlendirin.
403 Forbidden
403 çoğunlukla şu durumlardan biridir:
- İstek, WAF filtreleme gibi platform taraflı bir kural tarafından engellenmiştir
- Token veya route, istenen model ya da istek biçimini kullanma iznine sahip değildir
- Seçilen model, gönderdiğiniz gelişmiş parametrelerden birini reddediyordur
İlk yapılacaklar:
- Bilinen şekilde sorunsuz çalışan bir model üzerinde çok basit bir metin isteğiyle yeniden deneyin.
- Gelişmiş alanları ve provider’a özgü parametreleri kaldırın, ardından bunları kademeli olarak geri ekleyin.
- Yanıt bir request id içeriyorsa, support ile iletişime geçmeden önce bunu saklayın.
Mesajda group veya channel gibi dahili terimler geçiyorsa, bunları istemci tarafında ilk teşhis edilecek şeyler olarak değil, yönlendirme ayrıntıları olarak değerlendirin. Pratik çözüm yine önce token, model ve istek biçimini doğrulamaktır.
Yanlış base URL veya yanlış path
Comet üzerinde bir path hatası şu şekillerde ortaya çıkabilir:
- Bir yönlendirme
- İstemciniz yönlendirmeleri izliyorsa JSON olmayan bir HTML yanıtı
- SDK’nız içinde bir parsing hatası
- API katmanına düzgün şekilde hiç ulaşmayan bir istek
Bu base URL’yi tam olarak kullanın:
Önerilen kontroller:
- base URL’nin
/v1 içerdiğini doğrulayın.
- Endpoint path’in dokümantasyonla tam olarak eşleştiğini doğrulayın.
- Path sorunlarını debug ederken otomatik yönlendirme takibini devre dışı bırakın.
413 Request Entity Too Large
413 görüyorsanız, önce bunu bir istek boyutu sorunu olarak ele alın. Yaygın şüpheliler şunlardır:
- Büyük base64 payload’ları
- Satır içi gömülü aşırı büyük görseller veya ses dosyaları
- Çok büyük multipart veya JSON body’leri
Yapılması gerekenler:
- Ekli içeriği küçültün veya sıkıştırın.
- Büyük işleri daha küçük isteklere bölün.
- Nedenin yalnızca düz metin uzunluğu olduğunu varsaymayın.
429 Too Many Requests
429 yeniden denenebilir olarak değerlendirilmelidir:
- Jitter ile exponential backoff kullanın.
- Burst concurrency’yi azaltın.
- Hangi route ve modelin önce doygunluğa ulaştığını görebilmek için request logging’i açık tutun.
Yeniden kullanılabilir bir retry deseni için Chat Completions sayfasındaki backoff örneğine bakın.
503, 504, and 524
Bu durum kodları sunucu taraflı veya timeout sınıfı hatalardır.
Pratik rehber:
503: route veya provider hizmeti geçici olarak kullanılamıyor504 ve 524: platform, edge veya provider hizmeti arasındaki timeout sınıfı hatalar
Yapılması gerekenler:
- Backoff ile yeniden deneyin.
request id, endpoint, model ve timestamp bilgisini saklayın.- Aynı hata birden fazla yeniden denemede tekrarlanıyorsa, bu bağlamla birlikte support ile iletişime geçin.
Destek ile iletişime geçmeden önce
Önce şu ayrıntıları toplayın:
- HTTP yöntemi
- Endpoint yolu
- Model ID
- Anonimleştirilmiş istek body JSON’ı (çoğu API çağrısı için en faydalı tek öğe budur)
- Hatalı istek bunları kullandıysa sorgu parametreleri
- İstemciniz yakaladıysa tam yanıt body’si
- Tam HTTP durum kodu
- Tam
error.message
- Herhangi bir
request id
- Yaklaşık zaman damgası
- Aynı isteğin başka bir model veya başka bir token ile çalışıp çalışmadığı
Hata veren route, düz bir JSON body yerine dosya yüklemeleri (görüntü düzenleme, ses yükleme, video oluşturma vb.) kabul ediyorsa, gönderilen eşdeğer payload’ı paylaşın:
- Dosyayla birlikte gönderdiğiniz alan adları ve metin değerleri
- Dosya adı, dosya türü ve yaklaşık dosya boyutu
- Dosyanın doğrudan mı yüklendiği, URL ile mi referans verildiği veya base64 olarak mı gömüldüğü
Bir hatayı yeniden üretmenin en etkili yolu, tam olarak anonimleştirilmiş istek payload’ıdır. Çoğu API çağrısı için bu, ham istek body JSON’ı anlamına gelir. Dosya yükleme route’ları içinse bu, alan listesi artı dosya meta verileri anlamına gelir.
