الأدلة الأساسية
التعامل مع أخطاء 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 الذي أنشأه |
413 | الطلب أو الملف المرفوع كبير جدًا | قلل المدخلات لتناسب حد النموذج أو نقطة النهاية الموثقة |
429 | تم الوصول إلى حد الطلبات | انتظر وفقًا لـ Retry-After |
500–504 | الخدمة غير متاحة أو حدث خطأ في الشبكة | أعد المحاولة فقط عندما تكون retryable بقيمة true، مع الالتزام بـ retry_after وحد أقصى للمحاولات |
رموز الخطأ الشائعة
| الرمز | ماذا يعني | ماذا يجب أن تغير |
|---|---|---|
invalid_api_key | مفتاح API مفقود أو غير صالح أو غير نشط أو ملغى | تحقق من ترويسة Authorization وقيمة المفتاح |
expired_api_key | انتهت صلاحية مفتاح API | أنشئ أو اختر مفتاحًا نشطًا |
insufficient_balance | رصيد الحساب لا يغطي الطلب | أضف رصيدًا، أو قلل الطلب، أو اختر نموذجًا أقل تكلفة |
quota_exceeded | وصل مفتاح API إلى حده الخاص | زد حد ذلك المفتاح أو استخدم مفتاحًا مصرحًا به آخر |
model_not_allowed | المفتاح لا يمكنه استخدام النموذج المطلوب | حدّث قائمة نماذج المفتاح أو اختر نموذجًا مسموحًا به |
model_not_found | معرف النموذج غير معروف أو غير متاح | اقرأ /v1/models واستخدم معرف نموذج حالي |
context_length_exceeded | المدخلات أطول مما يقبله النموذج | احذف السجل أو اختر نموذجًا بنافذة سياق أكبر |
rate_limit_exceeded | تم إرسال الكثير من الطلبات في النافذة الحالية | انتظر وفقًا لـ Retry-After |
payload_too_large | جسم الطلب أو الملف يتجاوز حد نقطة النهاية | قلل أو اضغط المدخلات |
all_channels_failed | لا يستطيع النموذج المحدد معالجة هذا الطلب | أعد المحاولة فقط عندما تكون retryable بقيمة true، مع الالتزام بـ retry_after وحد أقصى للمحاولات |
timeout_error | لم ينتهِ الطلب في الوقت المحدد | أعد المحاولة فقط عندما تكون العملية آمنة للتكرار |
لا يعني 503 all_channels_failed أو 503 delivery_tier_unavailable دائمًا وجود عطل مؤقت. إذا لم تتوفر خدمة للعملية المطلوبة ضمن مستوى Delivery المحدد، تكون retryable بقيمة false ولا يُرجع retry_after. لا تكرر الطلب نفسه. تحقق من توفر العملية ومستوى Delivery باستخدام GET /v1/models قبل اختيار نموذج آخر. تشابه الأسماء لا يثبت التوفر؛ ولا تُعرض البدائل غير المتحقق منها.
تتضمن بعض الأخطاء المتوافقة مع OpenAI حقولًا اختيارية مثل did_you_mean أو suggestions أو alternatives أو hint أو retryable أو retry_after. راجع الأخطاء التي يمكن للوكلاء (Agents) التعامل معها.
عندما يُنفَّذ الطلب عبر مسار Official ويرفض الخدمة المصدر (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 وحد أقصى للمحاولات |
| انقطاع الاتصال قبل أي استجابة | أحيانًا. بالنسبة لعمليات الإنشاء، تحقق مما إذا كانت المهمة أو الأثر الجانبي موجودًا بالفعل. |
| انقطاع البث بعد وصول المخرجات | لا تعتبرها استجابة كاملة. قد يؤدي التكرار إلى إنشاء مخرجات مختلفة أو فرض رسوم ثانية. |
بالنسبة لإنشاء الصور والفيديو والموسيقى والنماذج ثلاثية الأبعاد والعوالم، احفظ معرف المهمة (task ID) بمجرد إرجاعه. إذا انتهت مهلة طلب الإنشاء، تحقق من سجل المهمة قبل إرسال طلب إنشاء آخر.
احتفظ بمعرف الطلب (Request ID)
تتضمن ترويسات الاستجابة معرف طلب (Request ID) للتتبع. احفظه مع نقطة النهاية، والنموذج، والوقت، ومعرف المستخدم أو الوظيفة الخاص بك. بالنسبة للعمليات غير المتزامنة (async)، احفظ أيضًا task_id و billing_transaction_id عند توفرهما.
عند التواصل مع الدعم، قم بتضمين تلك المعرفات ومثال منقح. لا ترسل أبدًا مفاتيح API، أو رموز الإدارة (management tokens)، أو الوسائط الخاصة، أو الروابط الموقعة، أو المطالبات الخاصة الكاملة.