API hataları ve sorun giderme

Hata yanıtının biçimi

API hata döndürdüğünde gövde şu biçimdedir:

{
  "error": {
    "message": "Insufficient credits. Add credits at https://api.cocorex-ai.com to continue.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}

message insan okuması içindir (değişebilir); koddan kontrol için HTTP durum kodunu ve type alanını kullanın.

Hata kodları

Ücretlendirme: 5xx hatalarında (başarısız istekler) ücret alınmaz. 401 ve 402 zaten işlem yapılmadan reddedilir.

401: invalid_api_key

Olası nedenler:

• Anahtar yanlış kopyalanmış (başta/sonda boşluk, eksik karakter).
• Başlık yanlış: doğrusu Authorization: Bearer sk-cocorex-... (OpenAI biçimi) ya da x-api-key: sk-cocorex-... (Anthropic). Bearer kelimesini ve arada bir boşluğu unutmayın.
• Anahtar iptal edilmiş. Konsolda anahtar listesinde görünmüyorsa iptal edilmiştir.
• Başka bir hizmetin (OpenAI vb.) anahtarını kullanıyorsunuz; Cocorex anahtarları sk-cocorex- ile başlar.
• SDK'nın base URL değeri hâlâ eski sağlayıcıya işaret ediyor ve anahtar yanlış yere gidiyor.

Kontrol: aşağıdaki komutla anahtarı doğrulayın.

curl https://api.cocorex-ai.com/v1/models -H "Authorization: Bearer sk-cocorex-ANAHTARIN"

Model listesi dönüyorsa anahtar geçerlidir.

402: insufficient_credits

Bakiye bitti. Konsolda Kredi & fatura sayfasından kredi yükleyin ya da KREDI kodu uygulayın; yükleme sonrası istekler hemen çalışır. Önlem olarak bakiyenizi düzenli izleyin ve kritik uygulamalarda düşük bakiye uyarısı kurun (API hesabı ve kredi yükleme).

502 ve 504: Geçici model hataları

Model sağlayıcılarında kısa süreli sorunlar olabilir. Bunlar geçicidir; ücretlendirilmez. Çözüm: yeniden deneme.

Önerilen strateji (üstel geri çekilme):

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(api_key="sk-cocorex-...", base_url="https://api.cocorex-ai.com/v1")

def ask(messages, model="cocorex-1", retries=4):
    for attempt in range(retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except APIStatusError as e:
            if e.status_code in (500, 502, 504) and attempt < retries - 1:
                time.sleep(2 ** attempt + random.random())   # 1s, 2s, 4s...
                continue
            raise

Dikkat: 401 ve 402 için yeniden denemeyin; bunlar tekrar denemekle düzelmez.

Sürekli 502/504 alıyorsanız:

• Modeli değiştirin (örn. cocorex-1) ve deneyin.
• Zaman aşımı sürenizi artırın; bazı modeller (düşünen ya da arama yapan) cevabı geç verir. İstemci zaman aşımınızı en az 60 saniye yapın.
• Konsolda İstek günlüğünde hata zamanlarına bakın.

Akış (stream) sorunları

• Akış hiç başlamıyor: İstekte "stream": true var mı? Proxy/ara katman (nginx, CDN) yanıtı tamponluyor olabilir; tamponlamayı kapatın.
• Akış yarıda kesiliyor: Ağ kopmuş ya da 90 saniye boyunca hiç veri gelmemiştir (uzun sessizlik kesilir). O ana kadar üretilen kısım için ücretlendirilirsiniz. Sonucu tamamlamak için yeniden deneyin.
• Boş olaylar / [DONE]: OpenAI biçiminde akış data: [DONE] ile biter; istemciniz bunu işleyebilmeli (resmî SDK'lar işler).
• Anthropic biçimi: Olaylar content_block_delta tipindedir; event: satırlarını yok saymayın.

Biçim ve parametre hataları

• Anthropic biçiminde max_tokens zorunludur. Eksikse istek reddedilebilir.
• messages boş ya da yanlış rol: Roller system (yalnızca OpenAI biçimi), user, assistant olmalı; sohbet user ile bitmeli.
• Model adı: cocorex-1, deepseek-4.1-flash veya gpt-6-astra. Tanınmayan ad hata vermez, varsayılan modele düşer; yanlış yazdığınızı fark etmeyebilirsiniz. Günlükte Model sütununa bakarak doğrulayın.
• Çoklu ortam (görsel): /v1/chat/completions ucu metin bekler. Görsel içerikler için Anthropic biçimindeki /v1/messages ucunu kullanın; destek modele bağlıdır.
• Araç çağırma (tools): Akışsız modda araç blokları boş dönebilir; araç çağıran isteklerde stream: true kullanın.

Cevap "yanlış" ya da beklediğiniz gibi değil

Bu bir API hatası değil, modelin davranışıdır. Çözümler: sistem talimatını netleştirin, temperature değerini düşürün (tutarlılık için), modeli değiştirin, daha ayrıntılı bir istem yazın (prompt rehberi). Model kendi kimliğini sorduğunda, API'de kendisine verilen adı söyler; kendi sistem talimatınızla farklı bir kişilik tanımlayabilirsiniz.

Maliyet beklediğimden yüksek

İstek günlüğünde Giriş sütununa bakın. Çoğu zaman giriş tokenı şişiktir: sohbet geçmişi sürekli büyüyor, sistem talimatı çok uzun, ya da gpt-6-astra gibi sabit yükü olan bir model kullanılıyor (maliyet rehberi, günlük kullanımı).

Bize ne bildirmeli?

Sorun sürerse bize yazın ve şunları ekleyin (API anahtarınızı göndermeyin):

• İsteğin tarihi/saati ve kullandığınız model
• HTTP durum kodu ve hata gövdesi
• Mümkünse isteğin biçimi (içerik hassassa kısaltın)
• İstek günlüğündeki ilgili satırın ekran görüntüsü
• Akış kullanıp kullanmadığınız ve kullandığınız SDK/sürüm