Hatalar

2xx dışındaki her yanıt aynı JSON yapısına, yani OpenAI standardına sahiptir. Programlı işleme için error.code alanına, yeniden deneme politikası için status_code alanına göre eşleştirme yapın.

Hata yükü

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

HTTP durum kodları

Yaygın hata kodları

authentication_error

• Authorization: Bearer ... başlığını ayarlamayı unuttunuz.
• API anahtarı /app/keys üzerinden iptal edildi.
• Anahtarın öneki hâlâ yanlış ( sk-kn- ile başlamalı).

insufficient_quota

• Bu istek için cüzdan bakiyesi çok düşük → error.code, insufficient_balance değerinde. Hata; cüzdandaki tutarı (balance_usd), bu isteğin ayırdığı tutarı (needed_usd) ve iki bağlantıyı içerir: topup_url bağlantısı, yükleme tutarı önceden seçili olarak faturalandırma sayfasını açar; auto_recharge_url bağlantısı, otomatik bakiye yükleme ayarlarının bulunduğu sayfayı açar. Bu bağlantıların hiçbiri kendi başına ücret tahsil etmez.
• Anahtar başına aylık sınıra ulaşıldı. Sınır, takvim ayının başında (UTC) sıfırlanır. Sınırı /app/keys üzerinden yükseltin.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Yanıtta Retry-After başlığı yoksa insufficient_balance için yeniden denemeyi bırakın. Bu başlık, otomatik bakiye yüklemenin kayıtlı kartınızdan ödeme almaya başladığını belirtir; aynı isteğin birkaç saniye sonra başarılı olması gerekir.

permission_error

• Anahtarda IP izin listesi var ve çağrınız listedeki adreslerin dışında bir adresten geldi. İletide gördüğümüz adres belirtilir — bu adresi (veya CIDR bloğunu) /app/keys üzerinden ekleyin ya da her adrese izin vermek için izin listesini tamamen kaldırın.
• Bir aracıyı yeni bir ana makineye veya yeni bir NAT ağ geçidine taşımak ya da farklı bir ağdaki dizüstü bilgisayardan çalışmak bu adresi değiştirir. İzin listesi olmayan bir anahtar bu nedenle hiçbir zaman reddedilmez.

model_not_found

• Yazım hatalı kısa ad. Kanonik liste için /models sayfasını kullanın.
• Model şu anda devre dışı (üst akış kesintisi veya fiyatlandırma incelemesi nedeniyle).

upstream_error

Üst akış model sağlayıcısının, daha belirli bir koda dönüştüremediğimiz bir hata döndürdüğünü belirtir. Yanıt gövdesi özgün iletiyi içerir. Yaygın nedenler:

• Sağlayıcı tarafında aşırı yük.
• İçerik denetimi reddi (farklı bir istem deneyin).
• Bölge / kullanılabilirlik kısıtlamaları.

Yeniden deneme stratejisi

En basit ve güvenilir yöntem: yalnızca 429 / 5xx durumlarında sapmalı üstel geri çekilme uygulayın.

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Her deneme için bekleme süresini en fazla 30 saniye, toplam deneme sayısını ise 5 deneme ile sınırlayın.
• 4xx hatalarında (408 ve 429 hariç) yeniden denemeyin. Böyle yapmak yalnızca zaman kaybettirir.
• Görsel ve video oluşturma idempotent değildir: Yeniden deneme yeni bir oluşturma işlemidir ve başarılı olursa ücretlendirilir. Başarısız bir çağrıdan hiç ücret alınmamıştır, bu yüzden onu yeniden denemek güvenlidir. Video için POST /v1/videos, Idempotency-Key başlığını kabul eder: Aynı anahtarla tekrarlanan bir gönderim ilk görevi döndürür.
• Kendi kodunuzda yan etkilere yol açabilecek sohbet çağrılarında, uygulama katmanında bir idempotency anahtarı kullanarak yinelenen istekleri engelleyin.

Kontrol panelinden hata ayıklama

Başarılı veya başarısız her API çağrısı /app/usage adresinde görülebilir. İstek ve yanıtın tüm ayrıntılarını içeren sayfayı açmak için herhangi bir satıra tıklayın:

• İstemciye döndürülen HTTP durum kodu.
• Üst akış hata kodu (varsa).
• Gecikme, istek IP adresi, kullanıcı aracısı.
• Duruma göre filtreleme, belirli bir modeldeki tüm 422 hataları gibi örüntüleri bulmaya yardımcı olur.

Bir olayı bildirme

Çalışması gereken bir modelde sürekli 5xx hataları görüyorsanız, aşağıdakilerle birlikte support@kunavo.com adresine e-posta gönderin:

• Model kısa adı ve örnek istek gövdesi (gizli bilgileri çıkarın).
• Hataların oluştuğu zaman aralığı.
• Yanıttaki hata code + message.
• Mümkünse /app/usage/[id] adresinden bir kullanım günlüğü bağlantısı.

Bir iş günü içinde yanıt verilir; geliri etkileyen acil sorunlarda daha hızlı yanıtlanır.

Sonraki adımlar

• Faturalandırmanın 402 / kota hatalarına etkisi
• API anahtarı yönetimi