الإجابة المختصرة: لا تنتقل من Claude إلى GPT مع كل طلب فاشل. إن 401 تعني أن المصادقة يجب إصلاحها، و404 المرتبطة بالمسار تعني أن عنوان URL أو نقطة النهاية يجب تصحيحها. يمكن إعادة المحاولة مع إرجاء تصاعدي لخطأ 429 أو 5xx المؤقت؛ وإذا فشلت المحاولات المحدودة، يمكن لنموذج بديل متوافق أن يتولى المهمة.
هناك استثناء مهم: استجابة 500 مع error.code: invalid_request تظل مشكلة في الطلب نفسه. إعادة المحاولة — أو إرسال الحمولة المكسورة نفسها إلى نموذج آخر — لا تفعل سوى إخفاء العيب.
تم التحقق من هذه المقالة في 20 أغسطس 2026 مقابل وثائق CometAPI الخاصة بالأخطاء، وإعادة المحاولة، وعنوان URL الأساسي، وحدود المعدّل، والرجوع إلى نموذج بديل. وهي تغطي تصنيف الأخطاء فقط. لتصميم المسارات، واعتماديات المزود، وآليات التجاوز متعددة الطبقات، استخدم الدليل الكامل لبناء آليات الرجوع إلى نموذج بديل والدليل التقني للرجوع إلى نموذج بديل.
ابدأ بقرار إعادة المحاولة أم الإخفاق
| الحالة | المعنى المعتاد | إعادة المحاولة؟ | الرجوع إلى بديل؟ | الإجراء الأول |
|---|---|---|---|---|
| 401 | مفتاح مفقود أو غير صالح | لا | لا | أصلح رمز Bearer |
| 404 | مسار أو نقطة نهاية خاطئة | لا | لا | تحقق من عنوان URL الأساسي والمسار |
| 429 | حد المعدّل أو التشبّع | نعم | بعد محاولات محدودة | استخدم إرجاءً متزايدًا مع تذبذب (jitter) |
| 500 + invalid_request | طلب مشوّه | لا | لا | أصلح الحمولة (payload) |
| 500/503/504/524 | فشل مؤقت في المنصة أو المزوّد | نعم | بعد محاولات محدودة | احتفظ بمعرّف الطلب |
السؤال العملي ليس "هل فشل Claude؟" بل "هل يمكن أن ينجح نموذج آخر دون تغيير الجزء غير الصالح في هذا الطلب؟" تؤثر أخطاء المصادقة والمسار على الاتصال نفسه، لذا تغيير النموذج لا يحلها. قد تكون إخفاقات السعة المؤقتة والخوادم خاصة بمسار معيّن، لذا قد يفيد الرجوع إلى بديل.
اقرأ الخطأ قبل تبديل النماذج
استخدم حالة HTTP مع error.code وerror.message. كثير من أخطاء CometAPI تستخدم غلافًا مثل التالي:
{
"error": {
"message": "human-readable detail and request id",
"type": "comet_api_error",
"param": "problematic_parameter_or_empty",
"code": "error_code_or_empty"
}
}
لا تصنّف الخطأ بناءً على الرقم الأول من رمز الحالة فقط. قد تحمل 500 القيمة invalid_request، بينما قد يعيد مسار CometAPI الخاطئ إعادة توجيهًا أو HTML بدل JSON نظيف مع 404.
401 غير مصرّح: توقّف وأصلح المصادقة
عادةً ما تعني 401 أن مفتاح الـ API مفقود أو مشوّه أو منتهي أو مُحمّل من بيئة خاطئة. يجب أن يكون الترويسة:
Authorization: Bearer $COMETAPI_KEY
لا تعِد المحاولة ولا تبدّل النماذج. كلا المسارين يستخدمان المصادقة المكسورة نفسها. تحقق مما إذا كانت الخدمة المنشورة قد حمّلت سرًا قديمًا، أو ما إذا كانت هناك مسافات بيضاء أضيفت إلى المفتاح، أو ما إذا كان الطلب يصل إلى البيئة المقصودة. قم بتدوير المفتاح أو إعادة تحميله فقط عبر عملية إدارة الأسرار الخاصة بك.
404 غير موجود: أصلح عنوان URL قبل الرجوع إلى بديل
للطلبات المتوافقة مع OpenAI، استخدم عنوان URL الأساسي التالي حرفيًا:
https://api.cometapi.com/v1
قد يؤدي حذف /v1 أو تكرار مقطع المسار أو استخدام نقطة نهاية خاطئة إلى 404 أو إعادة توجيه أو استجابة HTML أو خطأ تحليل في SDK. عطّل تتبّع إعادة التوجيه التلقائي أثناء التصحيح وتحقق من مسار الطلب النهائي مقابل مرجع الـ API.
إذا قالت الاستجابة صراحة إن نموذجًا غير متاح أو غير موجود، فتحقق من معرّف النموذج في CometAPI Models API الحالي. لا تتعامل مع كل 404 على أنها عدم توفر النموذج. أضف رجوعًا خاصًا بالنموذج فقط بعد أن تلتقط هذا الإشارة تحديدًا وتختبرها.
429 عدد كبير من الطلبات: تراجع قبل الانتقال إلى بديل
إن 429 قابلة لإعادة المحاولة. استخدم إرجاءً تصاعديًا مع تذبذب، وخفّض الاندفاع في التواقت، وقِس أي مسار يتعرض للتشبّع. قد يحوّل إعادة المحاولة الفورية من كل عامل حدًا قصيرًا للمعدّل إلى ذروة حركة أكبر.
بعد عدد صغير ومحدود من المحاولات، قد يكون الرجوع إلى بديل مناسبًا عندما يدعم النموذج التالي الإدخال نفسه، وعقد الإخراج، والقدرات المطلوبة. الرجوع ليس مجانيًا: إنه يضيف زمناً إضافيًا وقد يغيّر التكلفة أو السلوك، لذا سجّل معدل استخدامه.
أخطاء 5xx: افحص الرمز ثم أعد المحاولة
عادةً ما تمثّل 500 و503 و504 و524 إخفاقات المنصة أو المزوّد أو فئة المهلة. احتفظ بمعرّف الطلب ونقطة النهاية والنموذج والوقت، ثم أعد المحاولة مع إرجاء تصاعدي. إذا استمر الفشل العارض نفسه بعد استنفاد ميزانية إعادة المحاولة، انتقل إلى المسار المتوافق التالي.
لكن افحص الجسم أولًا. عندما تحتوي 500 على error.code: invalid_request أو invalid_request_error، أصلح جسم الطلب وأعد المحاولة فقط بعد تغييره. تشمل الأسباب الشائعة حقل messages مفقودًا أو معلمة خاصة بمزوّد لا تقبلها نقطة النهاية المحددة.
استخدم سياسة صغيرة واحدة في الشيفرة
هذا المثال بلغة Python يبقي إعادة المحاولة والرجوع إلى بديل داخل التطبيق. يستخدم مفتاح CometAPI واحدًا، وعنوان URL الأساسي المتوافق مع OpenAI، ومتغيرات بيئية لمعرّفات نموذج Claude وGPT الحالية. يعيد المحاولة فقط عند الإخفاقات العارضة، ثم يبدّل النماذج بعد استنفاد ميزانية إعادة المحاولة.
import os, random, time
from openai import APIError, OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}
def complete(messages):
for model in MODELS:
for attempt in range(3):
try:
response = client.chat.completions.create(model=model, messages=messages)
return response.choices[0].message.content
except APIError as error:
status = getattr(error, "status_code", None)
code = getattr(error, "code", None)
if status in {401, 404} or code in {
"invalid_request", "invalid_request_error"
}:
raise
if status not in RETRYABLE:
raise
if attempt < 2:
time.sleep(2**attempt + random.random())
continue
break
raise RuntimeError("No configured route completed.")
print(complete([{"role": "user", "content": "Summarize this ticket."}]))
تم تعطيل إعادة المحاولات التلقائية في SDK حتى يمتلك التطبيق ميزانية إعادة المحاولة والرجوع الكلية. بدون ذلك التحكم، قد تضاعف إعادة محاولات الـ SDK مع إعادة محاولات التطبيق عدد الاستدعاءات وتؤخر الاستجابة النهائية.
اختبر السياسة دون تخمين
| الإشارة المحاكاة | النتيجة المتوقعة | ما الذي يجب ألا يحدث |
|---|---|---|
| 401 | ارفع فورًا | لا إعادة محاولة ولا استدعاء GPT |
| 404 | ارفع فورًا | لا رجوع إلى بديل يخفي مسارًا سيئًا |
| 429 | تراجع، ثم ارجع إلى بديل | لا عاصفة إعادة محاولات فورية |
| 500 + invalid_request | ارفع فورًا | لا تكرار للطلب المكسور |
| 503/504/524 | تراجع، ثم ارجع إلى بديل | لا سلسلة مسارات غير محدودة |
هذه اختبارات سياسة، وليست ادعاءات حول موثوقية المزوّدين المباشرة. في بيئة الاختبار، احقن الحالة وجسم الخطأ في المُصنِّف، وتحقق من عدد وترتيب الاستدعاءات، وأكد أن خطأك النهائي لا يزال يتضمن سياق الطلب الأصلي.
متى يكون الرجوع من Claude إلى GPT آمنًا فعليًا
يكون تبديل عائلات النماذج آمنًا فقط عندما يستطيع كلا المسارين تلبية العقد نفسه للتطبيق. طَبِّع حقول الطلب والاستجابة، واختبر المخرجات المهيكلة أو سلوك الأدوات على كلا النموذجين، وتحقق من أي قدرات مطلوبة للصور أو المستندات أو السياق أو الاستدلال قبل تمكين المسار.
كما يجب أن يراعي الرجوع الآثار الجانبية. إذا كان المسار الأول قد شغّل أداة بالفعل، أو كتب بيانات، أو بث استجابة جزئية، فإن تكرار الطلب كاملًا بشكل أعمى قد يكرر إجراءات أو يربك المستخدم. استأنف من نقطة حفظ أو أعد رد فشل مضبوطًا بدلًا من ذلك.
فحوصات إنتاجية تُبقي إعادة المحاولات محدودة
- ضع ميزانية كمون كلية واحدة. عدّ كل إعادة محاولة وكل رجوع ضمن المهلة نفسها.
- قُم بحدّ إعادة المحاولات. استخدم إرجاءً مع تذبذب وتوقف بعد حد صغير مُكوَّن.
- تحكّم في التواقت. خفّض الاندفاعات قبل مغادرة الطلبات للتطبيق.
- أضف قاطع دائرة. أوقف مؤقتًا استدعاء مسار يفشل على نحو متكرر.
- سجّل القرارات. التقط الحالة، ورمز الخطأ، ومعرّف الطلب، والنموذج، والمحاولة، والتأخير، وسبب الرجوع دون تخزين أسرار.
- تتبّع معدل الرجوع. زيادة مستمرة إشارة تشغيلية، لا مقياس نجاح عادي.
أسئلة شائعة
هل يجب أن يؤدي 401 إطلاقًا إلى رجوع إلى نموذج بديل؟
لا. أصلح مفتاح الـ API أو أعد تحميله. سيخفق نموذج مختلف يُستدعى عبر الاعتماديات غير الصالحة نفسها للسبب ذاته.
هل يجب أن يؤدي 404 إلى رجوع؟
ليس افتراضيًا. أصلح أولًا عنوان URL الأساسي أو نقطة النهاية. يجب أن يدخل فقط إشارة عدم توفر نموذج التي تم التحقق منها بشكل منفصل إلى مُصنِّف الرجوع.
كم مرة يجب أن أعيد المحاولة مع 429؟
استخدم حدًا صغيرًا تحدده على مستوى التطبيق ويتناسب مع ميزانية الكمون المواجهة للمستخدم. استخدم إرجاءً مع تذبذب وخفّض التواقت؛ لا تُعد المحاولة فورًا أو بلا حدود.
هل كل أخطاء 5xx قابلة لإعادة المحاولة؟
لا. الاستجابات المؤقتة 500 و503 و504 و524 مرشحة لإعادة المحاولة، لكن 500 مع invalid_request يجب أن تفشل بقوة حتى تُصلَح الحمولة.
هل يمكن لـ Claude وGPT استخدام الطلب نفسه دون تغيير؟
فقط للحقول المشتركة التي اختبرها تطبيقك. قد تتطلب معلمات خاصة بالمزوّد، وصيغ الأدوات، والمخرجات المهيكلة، والمدخلات متعددة الوسائط محولات. تغيير معرّف النموذج وحده لا يثبت التوافق.
أين توجد عملية الرجوع الكاملة؟
راجع How to Build Robust LLM Model Fallback Strategies للمعمارية الأوسع، وCometAPI model fallback guide لتفاصيل التنفيذ.
اجعل مُصنِّف الأخطاء هو حاجب البوابة
يكون الرجوع التلقائي مفيدًا عندما يكون ضيقًا وقابلًا للملاحظة. دع أخطاء المصادقة والمسار والطلبات المشوّهة تفشل بصخب. أعد المحاولة للحدود ومشكلات الخادم المؤقتة مع إرجاء تصاعدي، ثم انتقل إلى مسار متوافق فقط بعد استنفاد ميزانية إعادة المحاولة. تلك السياسة تجعل الرجوع عنصر ضبط موثوقية بدل أن يكون وسيلة لإخفاء أخطاء الضبط.