الأدلة الأساسية
التعامل مع أخطاء 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_restricted | HTTP 403. لا يمكن للحساب استخدام API | اتصل بالدعم مع ذكر معرف الطلب (Request ID) |
invalid_delivery_policy | HTTP 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_type | HTTP 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_unavailable | HTTP 503. الطلب صالح، لكن لا يمكن لـ TokenLab تسعير هذا المزيج من النموذج والعملية على المسارات التي يمكن للطلب استخدامها. لم يتم محاسبة الطلب، و retryable هو false | لا تكرر الطلب دون تغيير؛ اختر نموذجاً أو عملية أخرى، أو اتصل بالدعم مع ذكر معرف الطلب (Request ID) |
idempotency_conflict | HTTP 409. ينتمي Idempotency-Key لطلب مختلف. لم يقم TokenLab بتنفيذ هذا الطلب | أرسل طلباً جديداً بمفتاح جديد |
idempotency_replay_unavailable | HTTP 409. تم استخدام Idempotency-Key بالفعل، وليس لدى TokenLab نتيجة لإرجاعها له. لم يقم TokenLab بتنفيذ هذا الطلب مرة أخرى | إذا كان الطلب الأول لا يزال قيد التشغيل، انتظر وأعد المحاولة بنفس المفتاح. بخلاف ذلك أرسل مفتاحاً جديداً. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار |
idempotent_response_not_replayable | HTTP 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/generationsPOST /v1/images/generationsوPOST /v1/images/editsعندما ترجع مهمةPOST /v1/responsesمع"background": truePOST /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) خاصة كاملة.