Temel kılavuzlar
Ajanların işlem yapabileceği hatalar
Düz metinleri ayrıştırmak zorunda kalmadan hata kodlarını, yeniden deneme sürelerini ve model önerilerini kullanın
Bu sayfa, uygulamalar ve kodlama yapan ajanlar için makine tarafından okunabilir genel API hatalarını açıklamaktadır. Bu sayfa, çalışma alanı istek incelemelerine veya desteğe erişim sağlamaz. Çalışma alanınızdaki bir istek için istek sorun giderme bölümüyle 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 kısmını ayrıştırmayın.
Anthropic Messages ve Gemini API'leri kendi yerel hata formatlarını korurlar, 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ı
Aşağıdaki tüm alanlar error nesnesinin içinde görünür ve bazen bulunmayabilirler.
| Alan | Tür | Kullanım |
|---|---|---|
did_you_mean | string | Kullanımdan kaldırılmış bir modelin yerine geçen veya en yakın kullanılabilir model kimliği |
suggestions | array | İsteğe uygun olabilecek modeller |
hint | string | Kısa bir açıklama veya önerilen eylem |
retryable | boolean | Aynı isteğin daha sonra başarılı olup olamayacağı |
retry_after | number | Tekrar denemeden önce beklenecek saniye süresi |
balance_usd | number | USD cinsinden güncel bakiye |
estimated_cost_usd | number | Reddedilen isteğin tahmini maliyeti |
top_up_url | string | Bazı insufficient_balance hatalarında faturalandırma sayfası bağlantısı |
min_top_up_usd | number | Bazı insufficient_balance hatalarında USD cinsinden minimum yükleme tutarı |
İstemciniz her hatayı HTTP durumuna ve code değerine göre işlemeye devam etmelidir. Bu ek alanları gerekli alanlar olarak değil, yararlı bağlam bilgileri olarak değerlendirin.
Bilinmeyen model
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 zaten 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 /v1/models to list all available models."
}
}Yetersiz bakiye
402 insufficient_balance hatası, güncel bakiyeyi ve gereken tahmini tutarı veya bir yükleme bağlantısını ve minimum yükleme tutarını içerebilir. Uygulamanız bir yükleme bağlantısı, daha ucuz bir model veya daha küçük bir istek önerebilir.
{
"error": {
"message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
"type": "insufficient_balance",
"code": "insufficient_balance",
"retryable": false,
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-5.6-luna"},
{"id": "deepseek-v4.1-flash"}
],
"hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
}
}Model kullanılamıyor
503 all_channels_failed veya 503 delivery_tier_unavailable hatası her zaman geçici bir kesinti anlamına gelmez. Eğer istenen işlem seçilen Delivery katmanında tedarik edilemiyorsa, retryable değeri false olur ve retry_after atlanır. Aynı isteği tekrarlamayın. Başka bir model seçmeden önce GET /v1/models ile işlemi ve Delivery uygunluğunu kontrol edin. Benzer isimler uygunluk kanıtı değildir; doğrulanmamış alternatifler atlanır.
{
"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ı
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 exceeded (1000/min for user role). Please retry later.",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
}
}Bağlam çok uzun
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ı bulma
Modele özel bir API kullanmadan önce GET /v1/models/{model} üzerinden tokenlab.accepted_request_formats değerini okuyun.
| Değer | Uç Nokta |
|---|---|
openai_chat_completions | /v1/chat/completions |
openai_responses | /v1/responses |
anthropic_messages | /v1/messages |
gemini_generate_content | /v1beta/models/{model}:generateContent |
Kabul edilen bir format, uç noktayı 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 bulma
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, translation ve decision. Seçilen model kimliğini oluşturma isteğinde açıkça gönderin. TokenLab bunu sessizce farklı bir modelle değiştirmez.
Makine tarafından okunabilir genel bakış
Ajanlar, kompakt bir API genel bakışını şu adresten okuyabilirler:
GET https://api.tokenlab.sh/llms.txtBu dosya; ilk istek, yaygın uç noktalar, model filtreleri ve hata işleme rehberliğini içerir.
İsteği yeniden oynatmadan hatayı işleme
Bu örnek bir istek yapar, seçilen modeli korur ve yapılandırılmış kurtarma bilgilerini raporlar. SDK yeniden denemeleri devre dışı bırakılmıştır, böylece uygulamanız bir yeniden denemenin güvenli olup olmadığına karar verebilir. Açık bir seçim için model önerileri sunun; kabul edilen veya zaman aşımına uğrayan bir üretimi otomatik olarak yeniden oynatmayın. Zaman aşımına uğrayan bir isteği güvenli bir şekilde yeniden denemek için, Idempotency-Key ile güvenli yeniden deneme bölümünde gösterildiği gibi bir Idempotency-Key ile gönderin.
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