> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hata kodlarını ele alın
> CometAPI hata yanıtlarını sınıflandırmak ve yaygın istek hatalarında yeniden deneme veya düzeltme adımlarını uygulamak için bu kılavuzu kullanın.
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
| Status | Genellikle ne anlama gelir | Yeniden dene? | İlk işlem |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `400` | İstek, normal şekilde işlenmeden önce istek doğrulamasından geçemedi. | Hayır | `model`, `messages`, JSON yapısını ve alan türlerini doğrulayın. |
| `401` | API key eksik, hatalı biçimlendirilmiş veya geçersiz. | Hayır | `Authorization: Bearer $COMETAPI_KEY` değerini kontrol edin. |
| `403` | Erişim engellendi veya mevcut isteğe izin verilmedi. | Genellikle hayır | Bilinen şekilde doğru bir istekle yeniden deneyin ve önce modele özgü alanları kaldırın. |
| Yol hatası | Yanlış base URL veya yanlış endpoint yolu. Comet üzerinde bu durum temiz bir JSON `404` yerine `301` yönlendirmesi veya HTML olarak görünebilir. | Hayır | Tam olarak `https://api.cometapi.com/v1` kullanın ve hata ayıklarken yönlendirmelerin otomatik takip edilmesini devre dışı bırakın. |
| `429` | Rate limiting veya geçici doygunluk. | Evet | Jitter ile exponential backoff kullanın. |
| `500` with `error.code: invalid_request` | Hatalı biçimlendirilmiş bir istek, sunucu durumu yanıtı üzerinden ortaya çıktı. | Hayır | Yeniden denemeden önce istek gövdesini düzeltin. |
| `500`, `503`, `504`, `524` | Platform, sağlayıcı veya zaman aşımı sınıfı hata. | Evet | Backoff ile yeniden deneyin ve istek kimliğini saklayın. |
## Hata zarfı
Birçok CometAPI hatası bunun gibi bir hata gövdesi kullanır:
```json theme={null}
{
"error": {
"message": "...",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
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:
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
`your-model-id` değerini [CometAPI Models page](/tr/overview/models) ü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:
```json theme={null}
{
"error": {
"message": "field messages is required (request id: ...)",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
Bir `500` yanıtı `error.code: invalid_request` içeriyorsa, bunu bir istek sorunu olarak değerlendirin:
1. İstek gövdesini düzeltin.
2. Yükü endpoint şemasıyla karşılaştırın.
3. 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:
```json theme={null}
{
"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`
`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:
1. Bilinen şekilde sorunsuz çalışan bir model üzerinde çok basit bir metin isteğiyle yeniden deneyin.
2. Gelişmiş alanları ve provider'a özgü parametreleri kaldırın, ardından bunları kademeli olarak geri ekleyin.
3. 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:
```text theme={null}
https://api.cometapi.com/v1
```
Önerilen kontroller:
1. base URL'nin `/v1` içerdiğini doğrulayın.
2. Endpoint path'in dokümantasyonla tam olarak eşleştiğini doğrulayın.
3. 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:
1. Ekli 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. Nedenin yalnızca düz metin uzunluğu olduğunu varsaymayın.
## `429 Too Many Requests`
`429` yeniden denenebilir olarak değerlendirilmelidir:
1. Jitter ile exponential backoff kullanın.
2. Burst concurrency'yi azaltın.
3. 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](/api/text/chat) 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ıyor
* `504` ve `524`: platform, edge veya provider hizmeti arasındaki timeout sınıfı hatalar
Yapılması gerekenler:
1. Backoff ile yeniden deneyin.
2. `request id`, endpoint, model ve timestamp bilgisini saklayın.
3. 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.
Bu, destek geri dönüş süresini önemli ölçüde kısaltır.