ملاحظة الكاتب: يشرح هذا المقال كيفية فرز أخطاء API النماذج حسب رمز الخطأ، ومتى تجدر إعادة المحاولة، ومتى ينبغي التحويل إلى نموذج احتياطي، ومتى يجب التوقف لإصلاح الإعدادات. ويتضمن جدولًا لفرز الأخطاء، وقائمة للتحقق من النموذج الاحتياطي، وقائمة فحص قبل الإطلاق.
عند حدوث خطأ في API النموذج، حدّد نوعه أولًا، ثم قرّر كيفية التعامل معه. معظم أخطاء 4xx ناتجة عن مشكلة في الطلب أو الإعدادات، ولن تصلحها إعادة المحاولة؛ أما أخطاء 5xx و529 وانتهاء المهلة فتستحق إعادة المحاولة عددًا محدودًا من المرات، ثم التحويل إلى نموذج احتياطي إذا استمر الفشل؛ ولا تُعد تلقائيًا محاولة الطلبات التي لا تضمن عدم تكرار الأثر. إعادة المحاولة ليست الخيار الافتراضي، والتحويل إلى نموذج آخر لا يحل كل المشكلات. فكثير من حوادث الإنتاج لا تنتج عن تعطل النموذج، بل عن منطق معالجة أخطاء يحوّل عطلًا صغيرًا إلى رسوم مكررة، وعمليات كتابة مكررة في قاعدة البيانات، وفرض قيود على معدل الطلبات عبر سلسلة المعالجة بأكملها.
هذا المقال ليس ترجمة لقاموس رموز الأخطاء. إنه موجّه إلى المطورين الذين دمجوا API النماذج في بيئة إنتاج أو شبه إنتاج، ويركّز على كيفية تجنّب تفاقم المشكلة عند وقوع خطأ. ستجد فيه جدولًا لفرز رموز الأخطاء، واستراتيجية لإعادة المحاولة والانتقال إلى بديل، وقائمة للتحقق من قدرات النموذج الاحتياطي، وقائمة فحص عملية لما قبل الإطلاق. ويمكن تلخيص المقال في قاعدة واحدة: أصلح أخطاء 4xx أولًا، وفكّر في إعادة المحاولة عند أخطاء 5xx، وتوقف قبل إعادة محاولة طلب لا يضمن عدم تكرار الأثر.
تصنيف أخطاء API النموذج إلى 5 فئات: صنّف الخطأ أولًا، ثم قرر إعادة المحاولة أو التبديل
الخلاصة: تنقسم أخطاء API النموذج إلى خمس فئات، ولكل فئة طريقة معالجة شبه ثابتة. صنّف رمز الخطأ أولًا، وستصبح قرارات إعادة المحاولة والتبديل أكثر وضوحًا.
| فئة الخطأ | رموز الحالة المعتادة | مصدر المشكلة | الإجراء الافتراضي |
|---|---|---|---|
| خطأ في الطلب | 400، 404، 409، 422 |
متن الطلب أو المعلمات أو معرّف النموذج أو نقطة النهاية | لا تعد المحاولة؛ أصلح الطلب |
| خطأ في المصادقة | 401، 403 |
المفتاح أو ترويسات الطلب أو الأذونات أو المنطقة أو السياسة | لا تعد المحاولة؛ تحقق من المفتاح والأذونات |
| نفاد الحصة أو تقييد المعدل | 402، 429 |
الرصيد أو التزامن أو معدل الطلبات أو حصة النموذج | مع 402 توقّف؛ ومع 429 افحص متن الخطأ ثم طبّق تأخيرًا متزايدًا أو بدّل |
| عطل في الخدمة المزوّدة | 500، 502، 503، 529 |
البوابة أو الخدمة المزوّدة أو الضغط الزائد | أعد المحاولة عددًا محدودًا من المرات، ثم بدّل إذا استمر الفشل |
| انتهاء المهلة أو انقطاع التدفق | 408، 504، انتهاء مهلة الشبكة، انقطاع التدفق |
الاتصال أو المخرجات الطويلة أو بطء استجابة الخدمة المزوّدة | تحقق أولًا مما إذا كان الطلب قد نُفّذ أو فُرضت رسوم عليه، ولا تعد المحاولة إلا إذا كان الطلب متكافئ الأثر |
مفتاح التصنيف: التمييز بين «إعادة المحاولة» و«التبديل»
إعادة المحاولة تعني إرسال الطلب مجددًا باستخدام النموذج والمسار نفسيهما، وهي مناسبة للتعامل مع الاضطرابات المؤقتة. أما التبديل فيعني تغيير النموذج أو المسار، وهو مناسب عندما تستمر خدمة مزوّدة بعينها في عدم الاستجابة. تختلف تكلفة الخيارين: قد تزيد إعادة المحاولة زمن الانتظار وتؤدي إلى رسوم مكررة، بينما قد يغيّر التبديل جودة المخرجات وتوافق استدعاءات الأدوات والتكلفة.
لذلك، اتبع ثلاث خطوات بالترتيب: حدد فئة الخطأ، ثم تحقق مما إذا كان الطلب متكافئ الأثر، وأخيرًا اختر إعادة المحاولة أو التبديل أو التوقف. تخطي الخطوة الثانية هو الأخطر؛ فإعادة تنفيذ استدعاء أداة سبق تنفيذه قد تؤدي إلى عواقب تتجاوز مجرد «تكلفة إضافية».
لماذا تؤدي «إعادة محاولة كل الطلبات» إلى تفاقم أخطاء واجهة API للنموذج؟
الخلاصة: قد تبدو إعادة المحاولة عند كل خطأ خيارًا آمنًا، لكنها في الواقع تزيد التكاليف والآثار الجانبية واحتمال بلوغ حدود معدل الطلبات. وفي بيئة الإنتاج، غالبًا ما تكون المشكلات الناتجة عن هذا المنطق أصعب في التشخيص من الخطأ الأصلي.
المشكلة الأولى هي تكرار التكلفة. لا يعني انقطاع الاستجابة المتدفقة بالضرورة فشل الطلب؛ فقد يكون المزود قد ولّد بالفعل بعض الرموز، واحتسب تكلفتها. وإعادة إرسال الطلب دون تحقق قد تعني دفع تكلفة المهمة نفسها مرتين، خصوصًا عندما يكون الناتج طويلًا.
المشكلة الثانية هي تكرار التنفيذ. في سيناريوهات الوكلاء، قد يؤدي طلب واحد للنموذج إلى الكتابة في قاعدة بيانات أو إرسال رسالة أو إنشاء مهمة، بل حتى إجراء دفعة. إذا انتهت مهلة استدعاء أداة، فلن تعرف ما إذا كانت قد نُفذت بالفعل. وإعادة إرسال الطلب كاملًا في هذه الحالة قد تؤدي إلى إنشاء طلبَي شراء أو إرسال رسالتَي بريد إلكتروني.
المشكلة الثالثة هي تفاقم مشكلة حدود معدل الطلبات. يشير الخطأ 429 إلى أن المزود يطلب منك إبطاء معدل الطلبات؛ وإعادة المحاولة فورًا وبالتوازي لا تزيد إلا الضغط عليه. ومن الأمثلة الشائعة أيضًا إعادة المحاولة عند جميع أخطاء 4xx: فقد يكون سبب الخطأ 401 هو إدخال المفتاح بشكل خاطئ، لكن بعد عدة محاولات يُستنفد حد الطلبات، وتمتلئ السجلات بأخطاء 429، فيختفي السبب الجذري الحقيقي وراءها.
جدول فرز رموز الخطأ 401 و429 و500 و529: متى تعيد المحاولة ومتى تنتقل إلى بديل؟
الخلاصة: يغطي الجدول أدناه أكثر 14 رمز حالة شيوعًا في بيئات الإنتاج، ولا تستحق إعادة المحاولة إلا قلة منها. لا تنتقل إلى البديل إلا بعد التأكد من أن إعادة المحاولة لم تنجح. والمقصود بـ«الانتقال إلى بديل» في الجدول هو استخدام نموذج أو مسار احتياطي، ويعتمد المعنى الدقيق لكل رمز على محتوى الخطأ الفعلي ووثائق مزود الخدمة.
| رمز الحالة | المعنى الشائع | إعادة المحاولة؟ | الانتقال إلى بديل؟ | الإجراء |
|---|---|---|---|---|
400 |
خطأ في تنسيق الطلب أو معلماته | لا | لا | أصلح جسم الطلب وتحقق من الحقول وأنواعها |
401 |
مفتاح API غير صالح أو فشلت المصادقة | لا | لا | تحقق من مفتاح API وترويسة الطلب Authorization وعنوان URL الأساسي |
402 |
الرصيد غير كافٍ أو نفدت الحصة | لا | الانتقال إلى مسار آخر حسب الحالة | اشحن الرصيد أو انتقل إلى مسار تتوفر فيه حصة، وأرسل تنبيهًا |
403 |
رفض بسبب الصلاحيات أو المنطقة أو السياسة | لا | لا | تحقق من صلاحيات الحساب والإذن باستخدام النموذج والقيود الجغرافية |
404 |
النموذج أو نقطة النهاية غير موجودة | لا | لا | تحقق من معرّف النموذج ومسار نقطة النهاية |
408 |
انتهت مهلة الطلب | إعادة محدودة إذا كانت العملية متكررة الأثر | اختياري | تأكد من عدم تنفيذ العملية، ثم أعد المحاولة مرة واحدة |
409 |
تعارض أو عدم اتساق في الحالة | لا | لا | تحقق من حالة العملية وتجنب الكتابة المتزامنة |
422 |
فشل التحقق من المعلمات | لا | لا | أصلح المعلمات؛ ويشيع هذا الخطأ في مخطط المخرجات المهيكلة |
429 |
تجاوز حد الطلبات أو التزامن أو الحصة | أعد المحاولة بعد انتظار متزايد | انتقل إلى بديل إذا فشلت إعادة المحاولة | اقرأ محتوى الخطأ وRetry-After أولًا |
500 |
خطأ داخلي لدى المزود | إعادة محدودة | انتقل إلى بديل إذا استمر الفشل | سجّل معرّف الطلب ومحتوى الخطأ |
502 |
خطأ في البوابة | إعادة محدودة | يمكن الانتقال إلى بديل | ميّز بين مشكلة البوابة ومشكلة المزود |
503 |
الخدمة غير متاحة | إعادة محدودة | يمكن الانتقال إلى بديل | التزم بـRetry-After، واستخدم خدمة بديلة بقدرات أقل عند الضرورة |
504 |
انتهت مهلة البوابة | أعد المحاولة فقط إذا كانت العملية متكررة الأثر | يمكن الانتقال إلى بديل | تحقق أولًا مما إذا كانت المهمة قد نُفذت |
529 |
حمل زائد لدى المزود | إعادة محدودة | يمكن الانتقال إلى بديل | استخدم انتظارًا متزايدًا مع تأخير عشوائي، وانتقل إلى بديل إذا استمر الحمل الزائد |
لا يعني 429 دائمًا تجاوز حد المعدل: اقرأ تفاصيل الخطأ أولًا
يسهل إساءة تفسير الخطأ 429. فقد يشير إلى تجاوز حد المعدل، أو تجاوز حد الطلبات المتزامنة، أو نفاد حصة النموذج، وفي بعض الحالات قد يتعلق بالرصيد. عادةً ما تُحل مشكلة تجاوز حد المعدل بالانتظار لبضع ثوانٍ قبل إعادة المحاولة. أما عند نفاد الحصة، فلن يفيد تكرار المحاولة مهما بلغ عددها. والانتقال مباشرةً إلى أغلى نموذج لن يؤدي إلا إلى مضاعفة التكلفة، مع بقاء المشكلة.
اتبع الخطوات التالية للتعامل مع 429:
- اقرأ
Retry-Afterفي ترويسات الاستجابة، وانتظر المدة المحددة إن وُجد. - اقرأ حقل نوع الخطأ في متن الاستجابة للتمييز بين تجاوز حد المعدل (rate limit)، وتجاوز حد الطلبات المتزامنة (concurrency)، ونفاد الحصة (quota).
- عند وجود مشكلة في المعدل أو التزامن، أعد المحاولة مرة أو مرتين بعد الانتظار، وخفّض عدد الطلبات المتزامنة محليًا.
- عند وجود مشكلة في الحصة، أوقف إعادة المحاولة، وأطلق تنبيهًا، وانتقل إلى مسار تتوفر فيه حصة.
تنطبق فكرة مشابهة على 500. فهو لا يعني بالضرورة وجود خلل في النموذج نفسه؛ فقد تكون المشكلة في البوابة أو في الخدمة المصدر. سجّل أولًا معرّف الطلب (request id) وملخص تفاصيل الخطأ، فستحتاج إليهما لتشخيص المشكلة ومطابقة السجلات.
استراتيجية إعادة المحاولة عند أخطاء API النموذج: العدد والتراجع وRetry-After والإيدمبوتنس
الخلاصة: أعد المحاولة عند الأخطاء العابرة فقط، وبحد أقصى مرة أو مرتين، مع تطبيق التراجع الأُسّي وإضافة تأخير عشوائي. ولا تُجرِ إعادة المحاولة تلقائيًا إلا للطلبات التي تتمتع بخاصية الإيدمبوتنس. إذا لم تتحقق هذه الشروط الأربعة، فلا تُعِد المحاولة تلقائيًا.
| المعامل | القيمة المقترحة | التوضيح |
|---|---|---|
| الأخطاء القابلة لإعادة المحاولة | 429، 500، 502، 503، 504، 529، انتهاء مهلة الشبكة |
الاستثناءان الوحيدان من أخطاء 4xx هما 408 و429 |
| الحد الأقصى لإعادة المحاولة | 1-2 مرة | بعد ذلك، انتقل إلى بديل أو أطلق تنبيهًا، بدل الاستمرار في المحاولة |
| فاصل التراجع | 1s، 2s، 4s بزيادة أُسّية | أضف تأخيرًا عشوائيًا في كل مرة لتجنب إعادة المحاولة من عدة مثيلات في الوقت نفسه |
| Retry-After | التزم به أولًا إذا وُجد | له الأولوية على خوارزمية التراجع المحلية |
| شرط الإيدمبوتنس | يجب تحققه | لا تُعاد عمليات الكتابة واستدعاءات الأدوات وإرسال الرسائل والمدفوعات تلقائيًا افتراضيًا |
خطوات تطبيق استراتيجية إعادة المحاولة
- أنشئ دالة لتصنيف الأخطاء. تستقبل رمز الحالة ونص الخطأ، وتُرجع إحدى خمس فئات. اجعل بقية المنطق يعتمد على نتيجة التصنيف بدل التحقق من الأرقام في مواضع متفرقة من شيفرة التطبيق.
- حدّد ما إذا كان كل طلب يتمتع بخاصية الإيدمبوتنس. يمكن عادةً اعتبار توليد النصوص البسيطة والتلخيص والترجمة عمليات إيدمبوتنت؛ أما إذا كان الطلب يُشغّل أداة أو يُحدث عملية كتابة خارجية، فصنّفه على أنه غير إيدمبوتنت.
- تحقّق من حالة الطلبات غير الإيدمبوتنت أولًا. إذا انتهت مهلة استدعاء أداة، فاستعلم عن حالة المهمة أو قاعدة البيانات أولًا، وتأكد من أن العملية لم تُنفّذ قبل إعادة المحاولة. استخدم مفتاح إيدمبوتنس على مستوى التطبيق لمنع التكرار عند الحاجة.
- ضع حدًا أقصى للمدة الإجمالية. يجب تحديد سقف للوقت الذي تستغرقه جميع محاولات الطلب، حتى لا تستمر إعادة المحاولة في الخلفية بعد انتهاء مهلة طلب المستخدم.
- سجّل كل محاولة. سجّل على الأقل request id، ومعرّف النموذج، ورمز الحالة، وفئة الخطأ، وزمن الاستجابة، واستهلاك token، وعدد مرات إعادة المحاولة.
غالبًا ما تُهمَل الخطوة الأخيرة، لكنها ضرورية لمطابقة السجلات وتشخيص الأخطاء. إذا كنت تستخدم APIYI apiyi.com، فيمكنك عرض الاستخدام وسجلات الاستدعاءات حسب Key في لوحة التحكم. وبمطابقة request id المسجّل محليًا مع معلومات الخطأ على المنصة، يمكنك تحديد ما إذا كان الفشل قد حدث في البوابة أو لدى المزوّد أو في نص طلبك.
تعامل مع انقطاع البث على حدة. عند انقطاع طلب بث، تحقّق أولًا من عدد وحدات token التي وصلتك وما إذا كان المحتوى الناتج قابلًا للاستخدام، ثم قرّر ما إذا كنت ستتابع الكتابة أو تتخلص من المحتوى أو تعيد الطلب. وقبل إعادة طلب ذي مخرجات طويلة، تذكّر أن التوليد السابق قد يكون قد احتُسبت تكلفته بالفعل.
🎯 نصيحة لتشخيص الأخطاء: عند مواجهة أخطاء مثل
500و529يصعب تحديد مصدرها، احتفظ أولًا بنص الخطأ الأصلي وrequest id، ثم راجع الاستخدام والسجلات للفترة نفسها في لوحة تحكم APIYI apiyi.com. لا تستنتج سبب الخطأ من رمز الحالة وحده.
استراتيجية التحويل إلى نموذج احتياطي: تصنيف القدرات، وتعيين النماذج، والتحقق من التوافق
الخلاصة: قبل التحويل، يجب التأكد مسبقًا من أن النموذج الاحتياطي قادر على تنفيذ المهمة نفسها. إذا كان مسار التحويل يُستخدم لأول مرة عند وقوع العطل، فهناك احتمال كبير لحدوث عطل ثانٍ.
ابدأ بتصنيف النماذج إلى ثلاث فئات: رائدة، وعامة، وخفيفة. خصص لكل نوع من المهام نموذجًا رئيسيًا ونموذجًا احتياطيًا من الفئة نفسها أو من فئة مجاورة. لا تحوّل كل الطلبات إلى النموذج الأغلى؛ فقد يؤدي اضطراب واحد لدى مزود الخدمة إلى ارتفاع الفاتورة بشكل غير متوقع، كما أن استخدام نموذج رائد لكثير من المهام البسيطة لا يقدم فائدة إضافية.
| القدرة | النموذج الرئيسي | النموذج الاحتياطي | هل هو متوافق؟ | ما الذي يجب فعله قبل التحويل؟ |
|---|---|---|---|---|
| نافذة السياق | أدخل الحد الفعلي | أدخل الحد الفعلي | بانتظار التحقق | تأكد من استيعاب أطول مدخل فعلي، وإلا فضع استراتيجية للاقتطاع أولًا |
| استدعاء الأدوات | مخطط الأدوات، والاستدعاء المتوازي | كما في النموذج الرئيسي | بانتظار التحقق | تحقق من تنسيق إعادة معرّف الاستدعاء وبنية المعلمات |
| المخرجات المهيكلة | مخطط JSON أو JSON صارم | كما في النموذج الرئيسي | بانتظار التحقق | اختبر معدل النجاح باستخدام المخطط نفسه لتجنب الخطأ 422 |
| المدخلات متعددة الوسائط | الصور والصوت والفيديو | كما في النموذج الرئيسي | بانتظار التحقق | تأكد من تنسيقات المدخلات وحدود أحجامها |
| معلمة reasoning | مستوى الاستدلال أو حقل التفكير | كما في النموذج الرئيسي | بانتظار التحقق | احذف المعلمات غير المدعومة أو عيّنها إلى معلمات بديلة عند التحويل |
| التكلفة وحدود المعدل | وفقًا للوحة التحكم | وفقًا للوحة التحكم | بانتظار التحقق | قدّر التكلفة بعد التحويل وتأكد من كفاية الحدود |
| المناطق والامتثال | النطاق المسموح | النطاق المسموح | بانتظار التحقق | تأكد من أن مسار الاتصال الاحتياطي يقع ضمن المناطق المسموح بها ومتطلبات امتثال العمل |
يُنصح بملء جدول لكل نوع من المهام، وتسجيل النتائج التي تم التحقق منها فقط في عمود «هل هو متوافق؟»، بدلًا من الاعتماد على الانطباعات. معلمة reasoning هي الأكثر عرضة للمشكلات: فقد يتسبب حقل مستوى الاستدلال الذي يدعمه النموذج الرئيسي في إرجاع الخطأ 400 أو 422 عند إرساله إلى النموذج الاحتياطي. لذلك يجب أن تتضمن آلية التحويل طبقة لتكييف المعلمات، بدلًا من تمريرها كما هي.
ربط النماذج: اعتمد معرّفات النماذج الظاهرة في لوحة التحكم
من أكثر الأخطاء الشائعة عند التبديل كتابة معرّف النموذج بشكل غير صحيح، ما يؤدي إلى ظهور خطأ 404. يُنصح بالاحتفاظ بجدول يربط «الاسم المنطقي للنموذج» بمعرّفه الفعلي، بحيث تستخدم شيفرة التطبيق الاسم المنطقي فقط. عند استدعاء النماذج عبر APIYI apiyi.com، ارجع إلى لوحة التحكم والوثائق لمعرفة المعرّف الدقيق لكل نموذج وحالة توفره وسعره، واستخدم https://api.apiyi.com/v1 بوصفه base_url موحدًا. وبعد تعديل جدول الربط، نفّذ طلبًا تجريبيًا محدودًا قبل النشر.
التحقق من النموذج الاحتياطي وبوابة النماذج المتعددة: الاختبار المحدود والسجلات والتراجع التلقائي
الخلاصة: تحقّق من النموذج الاحتياطي باستخدام مهام حقيقية قبل إطلاقه، وافحص جودة المخرجات بعد التراجع إليه، بدلًا من الاكتفاء بالتأكد من أن رمز الحالة هو 200. تقلّل بوابة النماذج المتعددة تكلفة التبديل، لكنها لا تتحقق من الجودة نيابةً عنك.
التحقق من النموذج الاحتياطي في ثلاث خطوات
- طلبات الاختبار المحدود. اختر مجموعة من مهام العمل الحقيقية وأرسلها إلى النموذج الأساسي والنموذج الاحتياطي، باستخدام الموجه والأداة والمدخلات نفسها.
- مقارنة النتائج للمهمة نفسها. قارن معدل اجتياز الاختبارات وزمن الاستجابة ووقت ظهور أول token وتكلفة token ومعدل الإخفاق. وفي مهام استدعاء الأدوات، تحقّق أيضًا من توافق معرّف الاستدعاء وبنية المعلمات وبنية النتائج، بندًا بندًا.
- التحقق بعد التراجع. بعد حدوث التبديل الفعلي، تحقّق من المخرجات تلقائيًا، مثل التأكد من إمكانية تحليل JSON واكتمال الحقول الإلزامية وصحة معلمات الأدوات، وسجّل سبب التبديل ونتيجة التحقق.
ينبغي اختبار مسار التراجع دوريًا. يمكنك تحويل جزء صغير من حركة الطلبات يدويًا إلى النموذج الاحتياطي كل أسبوع، للتأكد من أن المسار لا يزال يعمل وتجنّب تعطل التبعيات أو المعلمات أو معرّف النموذج دون ملاحظة.
يُنصح بأن تتضمن السجلات الحقول التالية على الأقل:
- معرّف الطلب، ومعرّف النموذج، ونقطة النهاية، ورمز الحالة، وفئة الخطأ، وملخص محتوى الخطأ
- زمن الاستجابة، ووقت ظهور أول token، والوقت الإجمالي، وعدد محاولات إعادة المحاولة، والوجهة التي تم التبديل إليها
- عدد token للمدخلات والمخرجات، والاستفادة من ذاكرة التخزين المؤقت، والتكلفة المقدّرة
- اسم الأداة المستدعاة، ومعرّف الاستدعاء، وما إذا نُفّذ بنجاح
- سبب التبديل، وما إذا اجتازت المخرجات التحقق بعده
دور بوابة النماذج المتعددة في التعافي من الأعطال
إذا كنت تتكامل بنفسك مع عدة مزودين للتعافي من الأعطال، فعليك صيانة عدة مفاتيح ومجموعات SDK وصيغ للأخطاء على الأقل. أما باستخدام بوابة تجميع مثل APIYI على apiyi.com، فيكفي مفتاح واحد لاستدعاء النماذج الشائعة مثل OpenAI وClaude وGemini وDeepSeek وQwen. والواجهة متوافقة مع معيار OpenAI، كما تدعم الصيغ الأصلية لـ Claude وGemini. ويمكن وضع النموذجين الأساسي والاحتياطي في شفرة التكامل نفسها، بحيث تقتصر عملية التبديل على تغيير معرّف النموذج بدلًا من تغيير مسار التكامل بالكامل.
توفر المنصة أيضًا النشر على عقد متعددة والتوجيه الذكي والتراجع التلقائي وموازنة الأحمال، ما يساعد على امتصاص بعض الاضطرابات لدى المزودين. لكن التراجع التلقائي على مستوى البوابة لا يحل محل قرارات التطبيق: فلا يزال عليك تنفيذ فحوصات ضمان عدم تكرار الأثر، وإزالة استدعاءات الأدوات المكررة، والتحقق من المخرجات داخل شفرتك. والتقسيم الأكثر أمانًا للمسؤوليات هو أن تتولى البوابة ضمان التوافر على مستوى المسارات والعقد، بينما يضمن التطبيق صحة النتائج على مستوى المهام.
💡 نصيحة للتعافي من الأعطال: عند تصميم إعداد النموذجين الأساسي والاحتياطي، يمكنك أولًا استخدام مفتاح واحد على APIYI عبر apiyi.com لتشغيل مجموعة مهام الاختبار المحدود نفسها على كلا النموذجين، ثم إضافة التركيبات التي اجتازت التحقق إلى جدول ربط النماذج. ويمكن للمستخدمين الجدد البدء باستخدام الرصيد التجريبي المجاني للتحقق.
الأسئلة الشائعة حول أخطاء API للنماذج
الخلاصة: تغطي الأسئلة الخمسة التالية أكثر السيناريوهات إثارة للجدل في بيئات الإنتاج. وتستند الإجابات جميعها إلى المبدأ نفسه: قيّم الحالة أولًا، ثم اتخذ الإجراء.
Q1: هل أعيد المحاولة عند ظهور الخطأ 401؟
لا. يشير `401` إلى فشل المصادقة، ولن تؤدي إعادة المحاولة إلا إلى زيادة عدد الطلبات، وربما تحوّل المشكلة إلى خطأ `429`. تحقّق من صلاحية مفتاح API، وصحة تنسيق ترويسة الطلب `Authorization`، وأن عنوان Base URL والمفتاح ينتميان إلى المنصة نفسها. عند استخدام APIYI apiyi.com، يمكنك التحقق من حالة المفتاح في لوحة التحكم.
Q2: هل أغيّر النموذج فورًا عند ظهور الخطأ 429؟
لا يُنصح بتغييره فورًا. اقرأ أولًا محتوى الخطأ وترويسة `Retry-After`: إذا كان السبب تجاوز حد المعدل أو الطلبات المتزامنة، فعادةً تكفي إعادة المحاولة مرة أو مرتين بعد الانتظار وفق سياسة التراجع. انتقل إلى مسار بديل فقط عند نفاد الحصة. وعند التبديل، اختر نموذجًا احتياطيًا من المستوى نفسه، بدلًا من الانتقال دائمًا إلى أغلى نموذج.
Q3: هل أعيد الطلب إذا انقطع الإخراج المتدفق؟
لا تتعجل إعادة الطلب. انقطاع التدفق لا يعني بالضرورة فشل الطلب؛ فقد يكون المحتوى قد أُنتج بالفعل وترتبت عليه تكلفة. تحقّق أولًا من عدد الرموز المستلمة وإمكانية استخدام المحتوى: إن كان صالحًا، فاحتفظ به أو استكمل توليده. وإن لم يكن صالحًا وكان الطلب متماثل الأثر، فأعده مرة واحدة. تعتمد الفوترة الفعلية على الاستخدام المسجل في لوحة التحكم.
Q4: ماذا أفعل إذا نُفّذ استدعاء الأداة أكثر من مرة؟
الحل الأساسي هو ضمان تماثل الأثر على مستوى الأداة، باستخدام مفتاح تماثل أثر خاص بالتطبيق أو معرّف المهمة لإزالة التكرارات، بحيث يُنفّذ كل معرّف مرة واحدة فقط. إذا انتهت مهلة استدعاء الأداة، فتحقّق أولًا من حالة المهمة، ولا تعِد المحاولة إلا بعد التأكد من أنها لم تُنفّذ. وإذا حدث التكرار بالفعل، فتتبّع السجلات باستخدام معرّف الاستدعاء، ثم عوّض العمليات الزائدة أو ألغها.
Q5: ماذا لو أرجع النموذج الاحتياطي الرمز 200 لكن النتيجة غير صحيحة؟
يشير 200 إلى نجاح الطلب فقط، لا إلى نجاح المهمة. تحقّق من المخرجات تلقائيًا، مثل بنية JSON والحقول الإلزامية وصلاحية معاملات الأداة. يجب احتساب فشل التحقق ضمن معدل الفشل، وإطلاق تنبيه أو إحالته إلى المراجعة البشرية. وإذا فشل مزيج احتياطي معين في اجتياز معايير القبول بشكل متكرر، فأزِله من جدول التعيين وأعِد التحقق باستخدام اختبار الكناري.
قائمة التحقق قبل الإطلاق والخلاصة: متى تعيد المحاولة، أو تبدّل النموذج، أو تتوقف
الخلاصة: التحقق من القائمة التالية بندًا بندًا قبل الإطلاق أكثر موثوقية بكثير من إضافة منطق المعالجة على عجل بعد وقوع المشكلة. تذكّر هذه القاعدة: أصلح أخطاء 4xx أولًا، ولا تفكّر في إعادة المحاولة إلا مع أخطاء 5xx، وتوقف أولًا عند الطلبات غير متكررة الأثر.
| الرقم | بند التحقق | معيار النجاح |
|---|---|---|
| 1 | تحديد نوع الخطأ أولًا | يمكن تصنيف جميع رموز الحالة ضمن إحدى الفئات الخمس، ولا تُعاد محاولة الأخطاء المجهولة افتراضيًا |
| 2 | عدم إعادة محاولة أخطاء 4xx تلقائيًا | إصدار تنبيه أو إصلاح المشكلة مباشرةً عند ظهور 400 أو 401 أو 402 أو 403 أو 404 أو 409 أو 422 |
| 3 | تحديد إعادة المحاولة أو التبديل | إعادة المحاولة للأخطاء المؤقتة فقط، مرة أو مرتين كحد أقصى، مع تأخير متزايد وعشوائي |
| 4 | الالتزام بـ Retry-After | عند وجود ترويسة الاستجابة، تُعطى الأولوية للانتظار وفق مدتها |
| 5 | التحقق من تكرار الأثر | التوقف افتراضيًا عن استدعاءات الأدوات وعمليات الكتابة وإرسال الرسائل والدفع، ثم التحقق من الحالة قبل اتخاذ القرار |
| 6 | معالجة انقطاع البث | التحقق أولًا من الرموز المستلمة والتكلفة، دون إعادة الطلب تلقائيًا |
| 7 | التحقق من النموذج البديل | استكمال جدول قدرات النموذج والتحقق منه حسب نوع المهمة |
| 8 | ربط أسماء النماذج | تطابق الربط بين الاسم المنطقي ومعرّف النموذج مع لوحة التحكم |
| 9 | التحقق النهائي من المخرجات | التحقق من البنية والحقول بعد التبديل، بدلًا من الاكتفاء برمز 200 |
| 10 | السجلات والتدريب | اكتمال الحقول الأساسية والتدرب دوريًا على مسار الانتقال إلى البديل |
أبرز النقاط في معالجة أخطاء API للنماذج
- متى تعيد المحاولة: عند ظهور
429أو500أو502أو503أو529، أو انتهاء مهلة طلب متكرر الأثر، مع تحديد عدد المحاولات وزيادة التأخير بينها. - متى تبدّل النموذج: عند استمرار الفشل بعد إعادة المحاولة، أو استمرار عدم توفر الخدمة من المزوّد، أو نفاد الحصة، بشرط التحقق مسبقًا من النموذج البديل.
- متى تتوقف: عند أخطاء الإعداد من فئة 4xx مثل
401، وعند الطلبات غير متكررة الأثر التي لا تُعرف حالتها. - التبديل لا يعني النجاح: حتى بعد أن يُرجع النموذج البديل الرمز 200، يجب التحقق من المخرجات.
- تقسيم المسؤوليات بين البوابة والتطبيق: تتولى البوابة توفر مسارات الاتصال، بينما تبقى مسؤولية صحة المهمة في كود التطبيق.
لا تُقاس جودة معالجة الأخطاء بمدى كثرة إعادة المحاولة، بل بالقدرة على اتخاذ القرار الصحيح عند كل خطأ. ابدأ باستكمال تصنيف الأخطاء ووسم الطلبات بحسب تكرار أثرها وحقول السجل، ثم أدخل النماذج البديلة تدريجيًا. ويمكنك النظر في APIYI على apiyi.com كخيار للمسار البديل: مفتاح واحد يتيح الوصول إلى نماذج رائدة من عدة مزوّدين، ما يسهّل التحقق من النموذجين الأساسي والبديل والتبديل بينهما باستخدام الكود نفسه. راجع لوحة التحكم والوثائق لمعرفة الأسعار والتوفر.
📚 المراجع
- مركز توثيق APIYI: طرق التكامل، وقائمة النماذج، وتفاصيل الفوترة
- الرابط:
docs.apiyi.com -
ملاحظة: يُرجى الرجوع إلى الوثائق ولوحة التحكم لمعرفة معرّفات النماذج وأسعارها ومدى توفرها.
-
شرح دلالات رموز حالة HTTP: معنى ترويسات الاستجابة القياسية مثل
Retry-After - الرابط:
developer.mozilla.org/docs/Web/HTTP/Status - ملاحظة: يفيد هذا المرجع في فهم المعاني العامة لرموز 4xx و5xx، أما المعنى الدقيق فيُحدَّد وفقًا لمحتوى الخطأ الصادر عن كل منصة نماذج.
الكاتب: الفريق التقني في APIYI
للتواصل التقني: يسعدنا تواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI الرسمي apiyi.com، ولمزيد من موارد التكامل، يمكنكم زيارة مركز التوثيق docs.apiyi.com.
