إنتقل إلى المحتوى الرئيسي

الأخطاء وحدود المعدّل والموثوقية

متوسط

تتحدّث شيفرة الإنتاج إلى خدمة شبكية، لذا يجب أن تتوقّع الإخفاق. قليل من البنية هنا هو الفارق بين تكامل هشّ وآخر يُعتمد عليه.

خريطة الأخطاء​

حالات HTTP النموذجية التي ستتعامل معها:

الحالةالمعنىما العمل
400طلب غير صالحأصلح الحمولة؛ لا تُعد المحاولة كما هي
401مفتاح API خاطئ/مفقودتحقّق من بيانات الاعتماد
403غير مسموح بهتحقّق من الوصول/الصلاحيات
429تجاوز حدّ المعدّلتراجع وأعِد المحاولة (احترم retry-after)
500/529خطأ في الخادم / تحميل زائدأعِد المحاولة مع التراجع التدريجي

تُظهر حِزَم SDK هذه الأخطاء كـ استثناءات مُصنَّفة بأنواع، لتتفرّع بوضوح بدلًا من تحليل السلاسل النصية.

إعادة المحاولة مع التراجع التدريجي​

للأخطاء العابرة (429، 5xx)، أعِد المحاولة مع تراجع أُسّي + اضطراب عشوائي (jitter)، مع وضع حدّ أقصى:

import time, random
for attempt in range(5):
    try:
        return client.messages.create(...)
    except (RateLimitError, APIStatusError) as e:
        if attempt == 4 or not should_retry(e):
            raise
        time.sleep(min(2 ** attempt + random.random(), 30))

(كثير من حِزَم SDK تعيد المحاولة على الأخطاء العابرة تلقائيًا — اعرف الإعداد الافتراضي لعميلك قبل إضافة منطقك الخاص.)

حدود المعدّل​

تُطبَّق الحدود لكل حساب/طبقة (الطلبات والرموز في الدقيقة). عند بلوغ حدٍّ تحصل على 429 مع تلميحات توقيت. الاستراتيجيات: احترم retry-after، ونعّم الدفعات المفاجئة، وجمّع العمل غير المتزامن في حزم، واستخدم نموذجًا أرخص (اختيار نموذج) للخطوات عالية الحجم.

ترحيل النماذج​

معرّفات النماذج مؤرّخة/مُصدَّرة وتُهجَر مع الوقت. اعزل نفسك:

التالي​