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

التعامل مع أخطاء API

قراءة رموز الخطأ، وإعادة المحاولة فقط عند الضرورة، والاحتفاظ بمعرف الطلب (Request ID)

تعامل مع الأخطاء بناءً على حالة HTTP و code. تم كتابة message للبشر وقد تتغير دون إشعار مسبق.

تستخدم Chat Completions و Responses كائن error بنمط OpenAI. بينما تحتفظ Anthropic Messages و Gemini بتنسيقات الأخطاء الخاصة بها، لذا لا تستخدم مُحللاً (parser) واحداً لكل TokenLab API.

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "retryable": true,
    "retry_after": 30
  }
}

فقط message و type موجودان دائماً في الأخطاء المتوافقة مع OpenAI التي ينشئها TokenLab. تظهر الحقول الأخرى عندما تكون ذات صلة.

رموز الحالة (Status codes)

الحالةالمعنىالإجراء المعتاد
400حقل أو معرف نموذج أو مدخل غير صالحصحح الطلب؛ لا تكرره دون تغيير
401مفتاح API مفقود، أو غير صالح، أو منتهي الصلاحية، أو مُلغىاستبدل المفتاح
402الرصيد أو حد مفتاح API منخفض جداًاشحن الرصيد، أو ارفع الحد، أو قلل الطلب
403لا يمكن لهذا المفتاح استخدام المورد أو النموذج، أو أن الحساب مقيدغيّر أذونات المفتاح أو النموذج، أو اتصل بالدعم
404المورد غير موجود أو لم يعد متاحاًتحقق من المعرف ومفتاح API الذي أنشأه
409تم استخدام Idempotency-Key بالفعل: مع نص طلب مختلف (idempotency_conflict)، أو لطلب لا يمكن لـ TokenLab إرجاع نتيجته (idempotency_replay_unavailable, idempotent_response_not_replayable). لم يقم TokenLab بتنفيذ الطلب مرة أخرىاستخدم مفتاحاً جديداً لطلب جديد. لاتخاذ قرار بشأن إعادة المحاولة بنفس المفتاح، راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار
413الطلب أو الملف المرفوع كبير جداًقلل المدخلات لتتوافق مع حد النموذج أو نقطة النهاية الموثقة
429تم الوصول إلى حد الطلباتانتظر وفقاً لـ Retry-After
500–504الخدمة غير متاحة أو فشل في الشبكةأعد المحاولة فقط عندما يكون retryable هو true؛ احترم retry_after وحدد عدد المحاولات

رموز الخطأ الشائعة

الرمزماذا يعنيماذا تغير
invalid_api_keyمفتاح API مفقود أو غير صالح أو غير نشط أو مُلغىتحقق من ترويسة Authorization وقيمة المفتاح
expired_api_keyانتهت صلاحية المفتاحأنشئ أو اختر مفتاحاً نشطاً
insufficient_balanceرصيد الحساب لا يغطي الطلبأضف رصيداً، أو قلل الطلب، أو اختر نموذجاً أقل تكلفة
quota_exceededوصل مفتاح API إلى حده الخاصارفع حد ذلك المفتاح أو استخدم مفتاحاً معتمداً آخر
model_not_allowedلا يمكن للمفتاح استخدام النموذج المطلوبحدّث قائمة نماذج المفتاح أو اختر نموذجاً مسموحاً به
user_suspended, account_restrictedHTTP 403. لا يمكن للحساب استخدام APIاتصل بالدعم مع ذكر معرف الطلب (Request ID)
invalid_delivery_policyHTTP 400. ترويسة X-TokenLab-Delivery-Policy ليست auto أو verified أو officialأرسل إحدى القيم الثلاث، أو احذف الترويسة
model_not_foundمعرف النموذج غير معروف أو غير متاحاقرأ /v1/models واستخدم معرف نموذج حالي
context_length_exceededالمدخلات أطول مما يقبله النموذجاحذف السجل أو اختر نموذجاً بنافذة سياق أكبر
missing_required_parameterحقل مطلوب مفقود. يحدده param، على سبيل المثال model في طلبات الصوت والصورة، التي ليس لها نموذج افتراضيأرسل الحقل الذي يحدده param
invalid_valueيحتوي الحقل على قيمة لا يقبلها النموذج، على سبيل المثال قيمة reasoning_effort. تسرد الرسالة القيم المقبولةاستخدم إحدى القيم المدرجة
invalid_response_format_typeHTTP 400. response_format كائن بلا type قابل للاستخدام، أو بـ type لا تقبله نقطة النهاية هذه. قيمة param هي response_formatاضبط response_format.type على text أو json_object أو json_schema؛ وعند استخدام json_schema أرسل أيضاً json_schema.name و json_schema.schema
invalid_image_urlلا يمكن لـ TokenLab استخدام رابط الصورة: ليس رابط HTTP(S) صالحاً أو URI لبيانات صورة، أو أن مضيف الصورة لم يرجع الصورة. يحدد param الحقلأرسل رابط صورة HTTPS عام أو URI بيانات مدعوم
unsupported_model_capabilityلا يوجد مسار في فئة التوصيل (Delivery tier) المختارة يدعم معامل طلب، مثل العملية، أو resolution، أو aspect_ratio، أو duration، أو حقل وسائط مدخل، أو web_search_options، أو max_tokens. تذكر الرسالة كل معامل لم يتطابق، وعندما ينشرها النموذج، القيم المدعومةاحذف المعامل أو غيّره، أو اختر فئة توصيل أو نموذجاً آخر؛ لا تكرر الطلب دون تغيير
unpriceable_selectionطلب الفيديو يغفل عن محدد يعتمد عليه سعره، لذا لا يمكن لـ TokenLab تسعيره. يحدد param المحدداضبط الحقل الذي يحدده param
model_pricing_unavailableHTTP 503. الطلب صالح، لكن لا يمكن لـ TokenLab تسعير هذا المزيج من النموذج والعملية على المسارات التي يمكن للطلب استخدامها. لم يتم محاسبة الطلب، و retryable هو falseلا تكرر الطلب دون تغيير؛ اختر نموذجاً أو عملية أخرى، أو اتصل بالدعم مع ذكر معرف الطلب (Request ID)
idempotency_conflictHTTP 409. ينتمي Idempotency-Key لطلب مختلف. لم يقم TokenLab بتنفيذ هذا الطلبأرسل طلباً جديداً بمفتاح جديد
idempotency_replay_unavailableHTTP 409. تم استخدام Idempotency-Key بالفعل، وليس لدى TokenLab نتيجة لإرجاعها له. لم يقم TokenLab بتنفيذ هذا الطلب مرة أخرىإذا كان الطلب الأول لا يزال قيد التشغيل، انتظر وأعد المحاولة بنفس المفتاح. بخلاف ذلك أرسل مفتاحاً جديداً. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار
idempotent_response_not_replayableHTTP 409. ينتمي Idempotency-Key لطلب إنشاء انتهت مهمته بالفعل، ولا يمكن لـ TokenLab إرجاع استجابة الإنشاء الأصلية. يتضمن المستوى الأعلى من نص الاستجابة task_id بجانب error. لم يقم TokenLab بتنفيذ هذا الطلب مرة أخرىلا تكرر الطلب بهذا المفتاح. أرسل مفتاحاً جديداً فقط إذا كنت تريد مهمة جديدة
rate_limit_exceededتم إرسال الكثير من الطلبات في النافذة الحاليةانتظر وفقاً لـ Retry-After
all_channels_failedالنموذج المختار لا يمكنه خدمة هذا الطلبأعد المحاولة فقط عندما يكون retryable هو true؛ احترم retry_after وحدد عدد المحاولات
timeout_errorلم ينتهِ الطلب في الوقت المحددأعد المحاولة فقط عندما تكون العملية آمنة للتكرار

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

تتضمن بعض الأخطاء المتوافقة مع OpenAI حقولاً اختيارية مثل did_you_mean أو suggestions أو alternatives أو hint أو retryable أو retry_after. راجع الأخطاء التي يمكن للوكلاء التصرف بناءً عليها.

عندما يتم تشغيل طلب على مسار رسمي (Official route) وقامت الخدمة الأولية (upstream) برفض الطلب نفسه، مثل مدخلات لا تقبلها أو قرار سياسة محتوى، يحمل الخطأ أيضاً upstream: وهو message الخاص بالخدمة الأولية كما تم الإبلاغ عنه، بالإضافة إلى code و source (اسم الخدمة الأولية) عند معرفتهما. تحمل أخطاء Anthropic Messages و Gemini نفس الكائن داخل error الخاص بها. استمر في التفريع بناءً على code و type؛ قيم upstream.code محددة بواسطة الخدمة الأولية وقد تتغير.

قرارات إعادة المحاولة

الخطأهل تكرر نفس الطلب؟
400, 401, 402, 403, 404, 413لا. غيّر الطلب أو بيانات الاعتماد أو الرصيد أو الأذونات أو المدخلات.
429نعم، بعد التأخير الذي يوفره الخادم.
500–504أعد المحاولة فقط عندما يكون retryable هو true؛ احترم retry_after وحدد عدد المحاولات
انقطع الاتصال قبل أي استجابةنعم، عندما يكون الطلب مدرجاً في إعادة المحاولة بأمان باستخدام مفتاح التكرار ويحتوي على Idempotency-Key: أرسله مرة أخرى بنفس المفتاح والنص. بخلاف ذلك، تحقق أولاً مما إذا كانت المهمة أو الأثر الجانبي موجوداً بالفعل.
انقطع البث بعد وصول المخرجاتلا تعتبرها استجابة كاملة. التكرار قد يولد مخرجات مختلفة أو محاسبة ثانية.

بالنسبة لإنشاء الصور والفيديو والموسيقى والنماذج ثلاثية الأبعاد والعوالم، احفظ معرف المهمة (task ID) بمجرد إرجاعه. إذا انتهت مهلة طلب الإنشاء، أرسله مرة أخرى بنفس Idempotency-Key والنص للحصول على المهمة الأصلية. بدون مفتاح، تحقق من سجل المهمة قبل إرسال طلب إنشاء آخر.

إعادة المحاولة بأمان باستخدام مفتاح التكرار

انتهاء المهلة أو انقطاع الاتصال لا يخبرك ما إذا كان TokenLab قد نفذ الطلب. أضف ترويسة Idempotency-Key للطلبات المدرجة أدناه. عندها لا يمكن لإعادة محاولة نفس الطلب تنفيذه أو محاسبتك عليه مرة ثانية.

  • استخدم قيمة فريدة جديدة لكل عملية، على سبيل المثال UUID. يمكن أن يحتوي المفتاح على ما يصل إلى 255 حرفاً. يتجاهل TokenLab المفتاح الأطول، وبالتالي لا يتمتع الطلب بحماية التكرار: يتم تنفيذ إعادة المحاولة ومحاسبتك عليها مرة أخرى. POST /v1/messages/batches مختلف: فهو يرفض المفتاح الذي يزيد طوله عن 256 حرفاً بالخطأ 400.
  • احفظ المفتاح في سجل وظائفك قبل إرسال الطلب.
  • عند إعادة المحاولة، أرسل نفس مفتاح API، ونفس Idempotency-Key، ونفس النص.
  • بعد أي استجابة بخلاف 409 مع idempotency_replay_unavailable، لا تستخدم ذلك المفتاح مرة أخرى. أرسل أي محاولة جديدة بمفتاح جديد.
  • أوقف عمليات إعادة المحاولة في SDK (max_retries=0)، بحيث يقرر كودك متى يعيد استخدام المفتاح.

بدون الترويسة، كل إعادة محاولة هي طلب جديد.

الطلبات التي تنشئ مهمة

طلبات الإنشاء هذه تقبل Idempotency-Key:

  • POST /v1/videos/generations, POST /v1/music/generations, POST /v1/3d/generations, و POST /v1/worlds/generations
  • POST /v1/images/generations و POST /v1/images/edits عندما ترجع مهمة
  • POST /v1/responses مع "background": true
  • POST /v1/messages/batches

إذا انتهت مهلة طلب الإنشاء، أرسله مرة أخرى دون تغييرات. يرجع TokenLab نتيجة طلب الإنشاء الأصلي ولا يقوم بإنشاء أو إرسال أو محاسبة مهمة ثانية. عادةً ما تكون النتيجة هي المهمة الأصلية بنفس المعرف id (بالنسبة لـ Responses، كائن الاستجابة الأصلي)، وتستمر في استطلاع حالتها. بالنسبة لمهام الفيديو والموسيقى والنماذج ثلاثية الأبعاد والعوالم والصور، يمكن أن تكون النتيجة أيضاً الخطأ الأصلي عندما فشل طلب الإنشاء الأول. إذا كانت هذه المهمة قد انتهت بالفعل ولم يكن لدى TokenLab استجابة إنشاء مخزنة، ترجع إعادة المحاولة 409 مع الرمز idempotent_response_not_replayable، ويتضمن المستوى الأعلى من نص الاستجابة task_id.

إذا أرسلت نصاً مختلفاً بمفتاح قبله TokenLab بالفعل، يرفض TokenLab الطلب ولا ينشئ مهمة. ترجع طلبات إنشاء الفيديو والموسيقى والنماذج ثلاثية الأبعاد والعوالم 409 مع الرمز idempotency_conflict. ترجع Message Batches الخطأ 409 مع نوع الخطأ conflict_error. بالنسبة لمهام الصور وطلبات Responses مع background: true، لا يتم ضمان رمز الحالة ورمز الخطأ لهذه الحالة. لا تكرر الطلب بنفس المفتاح.

Chat Completions و Responses و Messages

POST /v1/chat/completions و POST /v1/responses بدون background و POST /v1/messages تنفذ طلباً بمفتاح معين مرة واحدة فقط. إعادة المحاولة بنفس المفتاح تحصل على إحدى هذه النتائج:

الموقفالنتيجة
الطلب الأول لا يزال قيد التشغيل409 مع الرمز idempotency_replay_unavailable
انتهى الطلب الأول بعد انقطاع اتصال عميلك. لم يتم بث الطلب، والنتيجة 1 ميجابايت أو أصغر، وأعدت المحاولة بنفس النص خلال 24 ساعة200 مع نص الاستجابة الأصلي والترويسة Idempotent-Replayed: true. لا يقوم TokenLab بتنفيذ أو محاسبة الطلب مرة أخرى
تم استخدام المفتاح بأي طريقة أخرى، على سبيل المثال: تلقيت النتيجة، أو تم بث الطلب، أو كانت النتيجة أكبر من 1 ميجابايت، أو مر أكثر من 24 ساعة409 مع الرمز idempotency_replay_unavailable
النص مختلف عن الطلب الأول409، عادةً مع الرمز idempotency_conflict. بعض الطلبات ترجع idempotency_replay_unavailable

الخطأ 409 بأي من الرموز يعني أن TokenLab لم ينفذ الطلب مرة أخرى. لا يمكن تنفيذ طلب مبثوث (streamed) بمفتاح مرتين، ولا يمكن لـ TokenLab إرسال مخرجاته مرة أخرى.

هذا المثال يعيد محاولة طلب Chat Completions انتهت مهلته بنفس المفتاح حتى يحصل على النتيجة:

import os
import time
import uuid
import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=120.0,
    max_retries=0,
)

def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
    key = str(uuid.uuid4())  # Save this key with your job record.
    for wait in waits:
        time.sleep(wait)
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                extra_headers={"Idempotency-Key": key},
            )
        except (openai.APITimeoutError, openai.APIConnectionError):
            continue  # No response: retry with the same key and body.
        except openai.ConflictError as exc:
            if exc.code != "idempotency_replay_unavailable":
                raise
            # The first attempt can still be running. A later retry returns its result.
    raise RuntimeError(f"No result for Idempotency-Key {key}")

إذا استمرت المحاولة الأخيرة في إرجاع idempotency_replay_unavailable، فلا يمكن لـ TokenLab إرجاع تلك النتيجة. أرسل الطلب بمفتاح جديد فقط إذا كان التشغيل الثاني والمحاسبة الثانية مقبولين.

احتفظ بمعرف الطلب (Request ID)

تتضمن ترويسات الاستجابة معرف طلب (Request ID) للتتبع. احفظه مع نقطة النهاية، والنموذج، والوقت، ومعرف المستخدم أو الوظيفة الخاص بك. بالنسبة للعمليات غير المتزامنة (async)، احفظ أيضاً task_id و billing_transaction_id عند وجودهما.

عند الاتصال بالدعم، قم بتضمين تلك المعرفات ومثال منقح. لا ترسل أبداً مفاتيح API، أو رموز الإدارة (management tokens)، أو وسائط خاصة، أو روابط موقعة، أو مطالبات (prompts) خاصة كاملة.

من الطلب إلى التحقيق والدعم

في هذه الصفحة