معالجة أخطاء API
تفشل استدعاءات الشبكة الحقيقية، ويعيش عميل LLM في الإنتاج أو يموت بحسب طريقة تفاعله. أكثر غريزة مفيدة هي تقسيم الإخفاقات إلى سلّتين: ما يستحق إعادة المحاولة (عثرة عابرة ستزول على الأرجح) وما يجب إصلاحه في الطلب (خطأ في استدعائك لن تنفع معه أي إعادة محاولة). يخبرك رمز حالة HTTP في أي سلّة أنت.
في الكود الحقيقي، تقوم بالتقاط الاستثناءات النمطية الخاصة بـ SDK، والتي يحمل كل منها .status_code (للتوضيح فقط -> نحن لا نستدعي الشبكة):
import anthropic
try:
resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
messages=history)
except anthropic.RateLimitError: # HTTP 429 -> back off and retry
...
except anthropic.APIStatusError as e: # any other 4xx/5xx, has e.status_code
if should_retry(e.status_code):
... # retry with backoff
else:
raise # 400/401/403/404 -> a bug in YOUR request, surface itالحاويات، حسب رمز الحالة:
- Retry ->
408(انتهت مهلة الطلب)،409(تعارض)،429(تم تقييد المعدل)، وأي خطأ خادم من500إلى599، مثل502،503(غير متاح) أو529(حمولة زائدة). هذه أخطاء عابرة: انتظر، ثم حاول مرة أخرى. عندما يحتوي الاستجابة على رأسretry-after، انتظر تلك المدة على الأقل. - أصلح الطلب ->
400(bad request)،401(bad API key)،403(forbidden)،404(wrong model or path). إعادة محاولة استدعاء خاطئ تستهلك الحصة فقط. - Unknown -> أي شيء آخر (بما في ذلك نجاح مثل
200): لا تفترض أنه آمن لإعادة المحاولة.
أنت تقوم ببناء وظيفتين صغيرتين. classify_error(status) تعيد اسم الحاوية: "retry"، أو "fix-request"، أو "unknown". should_retry(status) تعيد القيمة المنطقية -> True بالضبط عندما تكون الحالة في مجموعة إعادة المحاولة، وإلا False.
يقرر هذا الدرس هل إعادة المحاولة؛ ومهارة الانتظار بين المحاولات هي مهارة خاصة. يغطي نموذج production-patterns التراجع الأسي (مضاعفة التأخير في كل محاولة: 1 ثانية، 2 ثانية، 4 ثوانٍ ...)، وفوق ذلك أنت ADD jitter -> كمية عشوائية صغيرة إضافية من الانتظار -> حتى لا تقوم مجموعة من العملاء الذين تم رفضهم في نفس اللحظة بإعادة المحاولة جميعاً في نفس الوقت ويضغطوا على الخادم مرة أخرى (ظاهرة "القطيع الهائج"). ابنِ الكود بحيث يعيد جدول الحالة عدة إجابات مختلفة (429 -> retry، 400 -> fix-request، 200 -> unknown)، مما يعني أنه لا يمكن لثابت واحد فقط أن يمر.
اكتب classify_error(status) الذي يعيد "retry" لـ 408 (انتهاء مهلة الطلب)، و 409 (تعارض)، و 429 (تحديد معدل الطلبات) وكل خطأ خادم من 500 إلى 599 (529 يعني حملاً زائداً)، و "fix-request" لـ {400, 401, 403, 404}، و "unknown" لأي شيء آخر. اكتب should_retry(status) الذي يعيد القيمة المنطقية True بالضبط عندما يكون classify_error(status) هو "retry"، وإلا False. (هذه هي نفس القاعدة التي يستخدمها SDK الرسمي من Anthropic: هو يعيد محاولة هذه الحالات، وأخطاء الاتصال، مرتين افتراضياً، وينتظر بقدر ما يطلب retry-after header. في الكود الحقيقي تقوم غالباً بضبط max_retries بدلاً من كتابة هذا بنفسك؛ كتابته مرة واحدة تظهر لك ما يفعله.)
سيفتح هذا التمرين قريبا
أنهِ الدرس السابق ليفتح هذا الدرس. الدورة كاملة مجانية، ولا تحتاج إلى حساب، ويمكنك قراءة هذا الدرس الآن.
يقوم هذا المتصفح بحظر ملفات تعريف الارتباط لـ learn.floati.life، لذا لا يمكن فتح الدروس التي أنهيتها هنا بالترتيب. اسمح بملفات تعريف الارتباط لهذا الموقع وأعد التحميل.