الأدلة الأساسية

الأخطاء التي يمكن للوكلاء التعامل معها

استخدم رموز الخطأ، وتوقيت إعادة المحاولة، واقتراحات النموذج دون الحاجة إلى تحليل النصوص

تصف هذه الصفحة أخطاء API العامة القابلة للقراءة آلياً للتطبيقات ووكلاء البرمجة. لا تمنح هذه الصفحة حق الوصول إلى تحقيقات طلبات مساحة العمل أو الدعم. بالنسبة لطلب في مساحة العمل الخاصة بك، ابدأ بـ استكشاف أخطاء الطلبات وإصلاحها.

يمكن أن تتضمن أخطاء TokenLab المتوافقة مع OpenAI تلميحات منظمة للوكيل أو التطبيق. استخدم هذه الحقول عند توفرها؛ ولا تقم بتحليل message المقروء بشرياً لاتخاذ قرار بشأن ما يجب فعله.

تحتفظ واجهات برمجة تطبيقات Anthropic Messages و Gemini بتنسيقات الأخطاء الأصلية الخاصة بها، لذا فإن الإضافات الموجودة في هذه الصفحة تنطبق فقط على أخطاء Chat Completions و Responses المتوافقة مع OpenAI.

حقول الخطأ الاختيارية

تظهر جميع الحقول أدناه داخل كائن error وقد تكون غير موجودة.

الحقلالنوعالاستخدام
did_you_meanstringبديل لنموذج تم إيقافه، أو أقرب معرف نموذج متاح
suggestionsarrayالنماذج التي قد تناسب الطلب
hintstringشرح قصير أو إجراء مقترح
retryablebooleanما إذا كان يمكن للطلب نفسه أن ينجح لاحقاً
retry_afternumberالثواني التي يجب الانتظار قبل المحاولة مرة أخرى
balance_usdnumberالرصيد الحالي بالدولار الأمريكي
estimated_cost_usdnumberالتكلفة التقديرية للطلب المرفوض
top_up_urlstringرابط صفحة الفواتير، في بعض أخطاء insufficient_balance
min_top_up_usdnumberالحد الأدنى لإعادة الشحن بالدولار الأمريكي، في بعض أخطاء insufficient_balance

يجب أن يتعامل عميلك مع كل خطأ من خلال حالة HTTP و code الخاص به. تعامل مع هذه الحقول الإضافية كمعلومات سياقية مفيدة، وليست حقولاً مطلوبة.

نموذج غير معروف

يؤدي استخدام نموذج مكتوب بشكل خاطئ أو غير متاح إلى إرجاع 400 model_not_found. إذا كان did_you_mean موجوداً، فاعرضه للمستخدم أو أعد المحاولة فقط عندما يكون لمنتجك إذن بالفعل لتغيير النموذج المحدد.

{
  "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."
  }
}

رصيد غير كافٍ

يمكن أن يتضمن الخطأ 402 insufficient_balance الرصيد الحالي والمبلغ التقديري المطلوب، أو رابط إعادة الشحن والحد الأدنى لمبلغ إعادة الشحن. يمكن لتطبيقك تقديم رابط لإعادة الشحن، أو اقتراح نموذج أقل تكلفة، أو طلب أصغر.

{
  "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."
  }
}

نموذج غير متاح

لا يعني الخطأ 503 all_channels_failed أو 503 delivery_tier_unavailable دائماً وجود انقطاع مؤقت. إذا كانت العملية المطلوبة لا تتوفر في مستوى التسليم (Delivery tier) المحدد، فإن retryable تكون false ويتم حذف retry_after. لا تكرر نفس الطلب. تحقق من توفر العملية ومستوى التسليم باستخدام GET /v1/models قبل اختيار نموذج آخر. الأسماء المتشابهة لا تثبت التوفر؛ يتم حذف البدائل غير المؤكدة.

{
  "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."
  }
}

حد المعدل

بالنسبة للخطأ 429 rate_limit_exceeded، انتظر لعدد الثواني المحدد في retry_after أو استخدم ترويسة استجابة Retry-After القياسية.

{
  "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."
  }
}

السياق طويل جداً

لا يتم حل الخطأ 400 context_length_exceeded عن طريق إرسال نفس الطلب مرة أخرى. قم بتقصير المدخلات أو اسمح للمستخدم باختيار نموذج ذي نافذة سياق أكبر.

{
  "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."
  }
}

العثور على تنسيق API الصحيح

اقرأ tokenlab.accepted_request_formats من GET /v1/models/{model} قبل استخدام API خاص بنموذج معين.

القيمةنقطة النهاية (Endpoint)
openai_chat_completions/v1/chat/completions
openai_responses/v1/responses
anthropic_messages/v1/messages
gemini_generate_content/v1beta/models/{model}:generateContent

يؤكد التنسيق المقبول نقطة النهاية. لا تزال الأدوات والحقول الفردية قابلة للاختلاف حسب النموذج؛ تحقق من صفحة النموذج قبل الاعتماد عليها.

العثور على نموذج حسب المهمة

يمكن لـ Models API إرجاع قائمة مختصرة حالية للمهام غير المتعلقة بالدردشة:

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

القيم الصالحة لـ recommended_for هي image و video و music و 3d و tts و stt و embedding و rerank و translation و decision. أرسل معرف النموذج المختار صراحةً في طلب الإنشاء. لا يقوم TokenLab باستبداله تلقائياً بنموذج مختلف.

نظرة عامة قابلة للقراءة آلياً

يمكن للوكلاء قراءة نظرة عامة مضغوطة على API عبر:

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

تتضمن هذه النظرة طلباً أولياً، ونقاط نهاية شائعة، وفلاتر النماذج، وتوجيهات التعامل مع الأخطاء.

التعامل مع خطأ دون إعادة إرسال الطلب

يقوم هذا المثال بإجراء طلب واحد، ويحتفظ بالنموذج المحدد، ويقدم معلومات استرداد منظمة. يتم تعطيل عمليات إعادة المحاولة في SDK حتى يتمكن تطبيقك من تحديد ما إذا كانت إعادة المحاولة آمنة. اعرض اقتراحات النماذج لاختيار صريح؛ لا تقم بإعادة تشغيل عملية توليد مقبولة أو انتهت مهلتها تلقائياً. لإعادة محاولة طلب انتهت مهلته بأمان، أرسله مع Idempotency-Key، كما هو موضح في إعادة المحاولة بأمان باستخدام مفتاح التماثل.

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

في هذه الصفحة