Ana içeriğe atla
CometAPI hata yönetimi, istek sorunlarını, kimlik doğrulama sorunlarını ve yeniden denenebilir platform sorunlarını birbirinden ayırdığınızda en kolay hale gelir. Bu sayfa, CometAPI için temel hata rehberidir ve önce istemci tarafında neleri doğrulayabileceğinize odaklanır.
Bu rehber, mevcut CometAPI API üzerinde yapılan canlı kontrolleri temel alır. 400, 401 ve path/base URL hatalarını doğrudan doğruladık. 413, 429, 500, 503, 504 veya 524 durumlarını sınırlı testlerde yeniden üretmedik, bu nedenle bu durum kodlarına yönelik yönlendirme bilinçli olarak temkinlidir.

​
Hızlı Değerlendirme

StatusGenellikle ne anlama gelirRetry?İlk işlem
400İstek, başarılı şekilde yönlendirilmeden önce doğrulamadan geçemedi.Hayırmodel, messages, JSON yapısını ve alan türlerini doğrulayın.
401API anahtarı eksik, hatalı biçimlendirilmiş veya geçersiz.HayırAuthorization: Bearer <COMETAPI_KEY> değerini kontrol edin.
403Erişim engellendi veya mevcut isteğe izin verilmedi.Genellikle hayırBilinen şekilde çalışan bir istekle tekrar deneyin ve önce modele özel alanları kaldırın.
Path mistakeYanlış base URL veya yanlış endpoint path. Comet üzerinde bu durum temiz bir JSON 404 yerine 301 yönlendirmesi veya HTML olarak görünebilir.HayırTam olarak https://api.cometapi.com/v1 kullanın ve hata ayıklama sırasında yönlendirmeleri otomatik takip etmeyi kapatın.
429Rate limiting veya geçici doygunluk.EvetJitter ile exponential backoff kullanın.
500, 503, 504, 524Platform veya timeout sınıfı hata.EvetBackoff ile yeniden deneyin ve request id değerini saklayın.

​
Hata Zarfı

CometAPI tarafından döndürülen mevcut JSON hata zarfı şu şekildedir: 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
Birçok canlı hata mesajı, error.message içinde ayrıca bir request id içerir. Desteğe ihtiyaç duyduğunuzda bu değeri saklayın.

​
400 Bad Request

model atlandığında canlı API’den gözlemlediğimiz yanıt: 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
Pratikte 400, genellikle platform isteği model sağlayıcısına yönlendiremeden önce istek gövdesinin doğrulamadan geçemediği anlamına gelir. Yaygın nedenler:
  • model veya messages gibi gerekli alanların eksik olması
  • Geçersiz JSON yapısı
  • Bir alanın yanlış türle gönderilmesi
  • Seçili endpoint’in kabul etmediği sağlayıcıya özel parametrelerin yeniden kullanılması
Yapılması gerekenler:
  1. Bilinen şekilde çalışan, minimal bir istekten başlayın.
  2. İsteğe bağlı alanları tek tek geri ekleyin.
  3. İstek gövdesini API referansındaki endpoint şemasıyla karşılaştırın.
Bilinen şekilde çalışan minimal örnek: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
your-model-id değerini CometAPI Models page üzerindeki güncel model kimliklerinden biriyle değiştirin.

​
401 Invalid Token

Geçersiz bir anahtarla canlı API’den gözlemlediğimiz yanıt: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
Kontrol edilmesi gerekenler:
  1. Header tam olarak Authorization: Bearer <COMETAPI_KEY> olmalıdır.
  2. 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.
  3. 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

Sınırlı testlerde kararlı bir 403 yeniden üretemedik, bu yüzden tek bir eski mesaj şablonunu tüm tablo olarak değerlendirmeyin. Mevcut Comet dokümantasyonunda 403 en sık şu durumlardan biri olarak ele alınır:
  • İstek, WAF filtreleme gibi platform taraflı bir kural tarafından engelleniyordur
  • Token veya route, istenen model ya da istek şekliyle kullanılmaya yetkili değildir
  • Seçilen model, gönderdiğiniz gelişmiş parametrelerden birini reddediyordur
İlk olarak yapılması gerekenler:
  1. Bilinen şekilde çalışan bir modele çok basit bir metin isteğiyle yeniden deneyin.
  2. Gelişmiş alanları ve sağlayıcıya özgü parametreleri kaldırın, ardından bunları kademeli olarak geri ekleyin.
  3. Yanıt bir request id içeriyorsa, destekle 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 unsur olarak değil, yönlendirme ayrıntıları olarak değerlendirin. Pratik çözüm yine önce token, model ve istek şeklini doğrulamaktır.

​
Yanlış Base URL Veya Yanlış Path

Eski sayfanın en az doğru olduğu bölüm buydu. Mevcut Comet endpoint’lerine karşı yapılan canlı kontrollerde:
  • https://api.cometapi.com/chat/completions adresine yapılan POST isteği, https://www.cometapi.com/chat/completions adresine 301 yönlendirmesi döndürdü
  • https://api.cometapi.com/v1/not-a-real-endpoint gibi sahte bir API route’una yapılan POST isteği de https://www.cometapi.com/v1/not-a-real-endpoint adresine 301 yönlendirmesi döndürdü
Bu, bir path hatasının şu şekillerde ortaya çıkabileceği anlamına gelir:
  • Bir yönlendirme
  • İstemciniz yönlendirmeleri takip ediyorsa JSON olmayan bir HTML yanıtı
  • SDK’nız içinde bir ayrıştırma hatası
  • API katmanına temiz bir şekilde hiç ulaşmayan bir istek
Bu base URL’yi tam olarak kullanın: 
https://api.cometapi.com/v1
Önerilen kontroller:
  1. Base URL’nin /v1 içerdiğini doğrulayın.
  2. Endpoint path’inin dokümantasyonla birebir eşleştiğini doğrulayın.
  3. Path sorunlarını ayıklarken otomatik yönlendirme takibini devre dışı bırakın.

​
413 Request Entity Too Large

Aşırı büyük 8 MiB boyutunda bir JSON request body ile bile sınırlı bir testte 413 yeniden üretemedik; bu nedenle eski açıklamadaki prompt çok uzundu yaklaşımı fazla dardı. Eğer 413 görürseniz, bunu önce bir request size 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:
  1. Eklenen içeriği küçültün veya sıkıştırın.
  2. Büyük işleri daha küçük isteklere bölün.
  3. Bunun tek nedeninin düz metin uzunluğu olduğunu varsaymayın.

​
429 Too Many Requests

24 paralel GET /v1/models isteğinden oluşan sınırlı bir eşzamanlılık denemesi sırasında 429 yeniden üretemedik; dolayısıyla kesin eşik açıkça route, model ve platformun o anki durumuna bağlıdır. 429 durumunu yeniden denenebilir olarak değerlendirin:
  1. Jitter ile exponential backoff kullanın.
  2. Ani eşzamanlılık yükünü azaltın.
  3. Hangi route ve modelin önce doygunluğa ulaştığını görebilmek için request loglamayı açık tutun.
Yeniden kullanılabilir bir retry deseni için Chat Completions üzerindeki backoff örneğine bakın.

​
500, 503, 504, Ve 524

Sınırlı testlerde bu durum kodlarını yeniden üretemedik. Bunlar, kullanıcı hataları olarak değil, sunucu taraflı veya zaman aşımı sınıfındaki hatalar olarak belgelenmelidir. Pratik yönlendirme:
  • 500: dahili platform veya sağlayıcı taraflı hata
  • 503: route veya sağlayıcı hizmeti geçici olarak kullanılamıyor
  • 504 ve 524: platform, edge veya sağlayıcı hizmeti arasındaki zaman aşımı sınıfındaki hatalar
Yapılması gerekenler:
  1. Backoff ile yeniden deneyin.
  2. request id, endpoint, model ve zaman damgasını saklayın.
  3. Aynı hata birden fazla yeniden denemede tekrarlanıyorsa, bu bağlamla birlikte destekle iletişime geçin.

​
Destek ile İletişime Geçmeden Önce

Önce şu ayrıntıları toplayın:
  • HTTP yöntemi
  • Endpoint yolu
  • Model adı
  • Sanitize edilmiş istek gövdesi JSON’ı (çoğu API çağrısı için en faydalı tek öğe budur)
  • Başarısız olan istek bunları kullandıysa query parametreleri
  • İstemciniz bunu yakaladıysa tam yanıt gövdesi
  • Tam HTTP durumu
  • Tam error.message
  • Varsa herhangi bir request id
  • Yaklaşık zaman damgası
  • Aynı isteğin başka bir modelle veya başka bir token ile çalışıp çalışmadığı
Başarısız olan route düz bir JSON gövdesi yerine dosya yüklemeleri kabul ediyorsa (görsel düzenleme, ses yükleme, video üretimi vb.), 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 yoksa base64 olarak mı gömüldüğü
Bir hatayı yeniden üretmenin en hızlı yolu, tam sanitize edilmiş istek payload’ıdır. Çoğu API çağrısı için bu, ham istek gövdesi JSON’ı anlamına gelir. Dosya yükleme route’ları içinse bu, alan listesi ile dosya metadata’sı anlamına gelir.
Bu, destek dönüş süresini önemli ölçüde kısaltır.