Ajanların işlem yapabileceği hatalar

Bu sayfa, uygulamalar ve kodlama ajanları için makine tarafından okunabilen genel API hatalarını açıklar. Çalışma alanı istek incelemelerine veya desteğe erişim sağlamaz. Kendi istekleriniz için sorun giderme kılavuzundan başlayın.

OpenAI uyumlu TokenLab hataları, bir ajan veya uygulama için yapılandırılmış ipuçları içerebilir. Bu alanlar mevcut olduğunda bunları kullanın; ne yapacağınıza karar vermek için insan tarafından okunabilir message içeriğini ayrıştırmayın.

Anthropic Messages ve Gemini API'leri kendi yerel hata formatlarını korur, bu nedenle bu sayfadaki uzantılar yalnızca OpenAI uyumlu Chat Completions ve Responses hataları için geçerlidir.

İsteğe bağlı hata alanlarıCopy Anchor Link

Aşağıdaki tüm alanlar error nesnesi içinde görünür ve bulunmayabilirler.

İstemciniz her hatayı yine de HTTP durumu ve code değerine göre işlemelidir. Bu ekstra alanları gerekli alanlar olarak değil, yararlı bağlam bilgileri olarak değerlendirin.

Bilinmeyen modelCopy Anchor Link

Yanlış yazılmış veya kullanılamayan bir model 400 model_not_found hatası döndürür. Eğer did_you_mean mevcutsa, bunu kullanıcıya gösterin veya yalnızca ürününüzün seçili modeli değiştirme izni varsa yeniden deneyin.

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.6-terra",
    "suggestions": [
      {"id": "gpt-5.6-terra"},
      {"id": "gpt-5.6-luna"}
    ],
    "hint": "Did you mean 'gpt-5.6-terra'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Yetersiz bakiyeCopy Anchor Link

402 insufficient_balance hatası, güncel bakiyeyi ve gereken tahmini tutarı içerebilir. Uygulamanız bir bakiye yükleme bağlantısı, daha ucuz bir model veya daha küçük bir istek sunabilir.

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Model kullanılamıyorCopy Anchor Link

503 all_channels_failed veya 503 delivery_tier_unavailable her zaman geçici kesinti anlamına gelmez. Seçilen Delivery katmanında istenen işlemi sağlayan bir kaynak yoksa retryable değeri false olur ve retry_after döndürülmez. Aynı isteği tekrarlamayın. Başka bir model seçmeden önce GET /v1/models ile işlem ve Delivery kullanılabilirliğini kontrol edin. Benzer adlar kullanılabilirliği kanıtlamaz; doğrulanmamış alternatifler listelenmez.

{
  "error": {
    "message": "This model is unavailable for the requested operation and Delivery tier.",
    "type": "all_channels_failed",
    "code": "all_channels_failed",
    "retryable": false,
    "hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
  }
}

Hız sınırı (Rate limit)Copy Anchor Link

429 rate_limit_exceeded hatası için retry_after saniyesi kadar bekleyin veya standart Retry-After yanıt başlığını kullanın.

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Bağlam çok uzunCopy Anchor Link

400 context_length_exceeded hatası, aynı isteği tekrar göndererek çözülmez. Girdiyi kısaltın veya kullanıcının daha geniş bir bağlam penceresine sahip bir model seçmesine izin verin.

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Doğru API formatını bulmaCopy Anchor Link

Modele özel bir API kullanmadan önce GET /v1/models/{model} üzerinden tokenlab.accepted_request_formats değerini okuyun.

Kabul edilen bir format, endpoint'i doğrular. Bireysel araçlar ve alanlar modele göre değişiklik gösterebilir; bunlara güvenmeden önce model sayfasını kontrol edin.

Göreve göre model bulmaCopy Anchor Link

Models API, sohbet dışı görevler için güncel bir kısa liste döndürebilir:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Geçerli recommended_for değerleri şunlardır: image, video, music, 3d, tts, stt, embedding, rerank ve translation. Seçilen model ID'sini oluşturma isteğinde açıkça gönderin. TokenLab bunu sessizce farklı bir modelle değiştirmez.

Makine tarafından okunabilir genel bakışCopy Anchor Link

Ajanlar, kompakt bir API genel bakışını şu adresten okuyabilir:

GET https://api.tokenlab.sh/llms.txt

Bu dosya; ilk istek, yaygın endpoint'ler, model filtreleri ve hata işleme rehberliğini içerir.

İsteği tekrar göndermeden hatayı işleyinCopy Anchor Link

Örnek tek istek gönderir, seçilen modeli korur ve yapılandırılmış hata bilgisini gösterir. SDK otomatik yeniden denemeleri kapalıdır. Model önerilerini açık bir seçim için kullanıcıya sunun; kabul edilmiş veya zaman aşımına uğramış üretim isteklerini otomatik tekrarlamayın.

import os
from openai import OpenAI, APIStatusError

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    try:
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Reply only with OK."}],
        )
        print(response.choices[0].message.content)
    except APIStatusError as exc:
        body = exc.body if isinstance(exc.body, dict) else {}
        error = body.get("error", body)
        if not isinstance(error, dict):
            error = {}
        print({
            "status": exc.status_code,
            "request_id": exc.request_id,
            "code": error.get("code"),
            "hint": error.get("hint"),
            "suggested_model": error.get("did_you_mean"),
            "retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
        })
        raise