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

متوسط

What you'll learn

• اقرأ خريطة أخطاء HTTP واعرف أي رموز الحالة يجب إعادة محاولتها مقابل إصلاحها
• أعِد محاولة الأخطاء العابرة مع تراجع أُسّي واضطراب عشوائي، مع وضع حدّ أقصى
• تعامل مع حدود المعدّل عبر retry-after والتنعيم والتجميع في حزم والنماذج الأرخص
• اعزل شيفرتك عن إهمال النماذج وعمليات ترحيلها

آخر تحقّق: 2026-06-20.

تتغيّر رموز الحالة الدقيقة والترويسات وطبقات حدود المعدّل — تأكّد منها في وثائق الأخطاء/حدود المعدّل الرسمية.

تأكّد من المصدر الرسمي.

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

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

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

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

Pro tip

• تُظهر حِزَم 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))

Watch out

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

حدود المعدّل

تُطبَّق الحدود لكل حساب/طبقة (الطلبات والرموز في الدقيقة). عند بلوغ حدٍّ تحصل على 429 مع تلميحات توقيت. استراتيجيات للبقاء تحت السقف:

Guided walkthrough1 of 4

1. عند الحصول على 429، اقرأ تلميح التوقيت في الاستجابة وانتظر تلك المدّة قبل إعادة المحاولة.

راجع اختيار نموذج لانتقاء النموذج المناسب للخطوات عالية الحجم.

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

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

• اقرأ معرّف النموذج من الإعدادات، لا من قيم حرفية متناثرة.
• راقب عمليات الإهمال — راجع مراقبة الإهمال والترحيل وجدول النماذج.
• أعِد تشغيل تقييماتك عند تبديل النماذج.

Key takeaways

• الأخطاء 400/401/403 هي خطؤك — أصلح الطلب أو بيانات الاعتماد، ولا تُعد المحاولة بشكل أعمى. أما 429 و500/529 فقابلة لإعادة المحاولة.
• أعِد محاولة الأخطاء العابرة مع تراجع أُسّي + اضطراب عشوائي، مع وضع حدّ أقصى (مثل min(2 ** attempt + random(), 30)).
• عند 429: احترم retry-after، ونعّم الدفعات المفاجئة، وجمّع العمل غير المتزامن في حزم، ووجّه الخطوات عالية الحجم إلى نموذج أرخص.
• اقرأ معرّفات النماذج من الإعدادات، وراقب عمليات الإهمال، وأعِد تشغيل التقييمات عند ترحيل النماذج.

اختبر نفسك

0/4

1. 1حصلت على خطأ 400 طلب غير صالح. ماذا يجب أن تفعل؟
2. 2أي رموز الحالة هي التي يجب أن تعيد محاولتها مع التراجع التدريجي؟
3. 3لماذا نضيف اضطرابًا عشوائيًا (jitter) إلى التراجع الأُسّي؟
4. 4أيٌّ مما يلي ليس استراتيجية مقترحة لحدود المعدّل؟

التالي

• الأمان والرفض والبدائل الاحتياطية
• الرموز والتسعير
• بناء الوكلاء على الواجهة البرمجية