فشل طلب Claude API لا يعني دائمًا أن النموذج رفض محتوى السؤال. فقد يكون السبب صيغة الطلب أو المفتاح أو الفوترة أو حد الاستخدام أو ضغط الخدمة. هذا دليل للتحضير لعام 2027 وفق التوثيق العام المتاح في 27 أكتوبر 2026، ولا يتناول حسابًا بعينه.
ابدأ بالرمز ونوع الخطأ
400 invalid_request_error: مشكلة في صيغة الطلب أو محتواه، وقد يستخدم أيضًا عند بلوغ حد إنفاق تضعه المؤسسة أو مساحة العمل وفق الحالة.401 authentication_error: مشكلة في مفتاح المصادقة، مثل كونه غير صالح أو ملغى أو منتهيًا.402 billing_error: مشكلة في بيانات الفوترة أو الدفع.403 permission_error: المفتاح لا يملك صلاحية المورد المطلوب.404 not_found_error: المسار أو المورد المطلوب غير موجود.409 conflict_error: تعارض مع الحالة الحالية لمورد يحتاج معالجة قبل إعادة الطلب.
إعادة المحاولة بالطلب نفسه لا تصلح تلقائيًا مفتاحًا ملغى أو مسارًا خاطئًا أو صلاحية ناقصة. صنف السبب أولًا، ولا تسجل قيمة المفتاح في سجل التشخيص أو ترسلها ضمن طلب دعم.
حجم الطلب ليس عدد الرموز وحده
يشير 413 request_too_large إلى تجاوز حجم الطلب بالبايت. الحدود الموثقة هي32ميجابايت لواجهتيMessagesوعدالرموز،و256ميجابايت للدفعات،و500ميجابايت للملفات. تختلف هذه الحدود عن سعة السياق وعدد رموز الإجابة.
429 ليس دائمًا انتظارًا قصيرًا
قد ينتج 429 rate_limit_error من حد معدل الطلبات أو سقف الإنفاق الشهري لشريحة الاستخدام أو حد إنفاق مساحةClaude Code. وفي حالة سقف إنفاق الشريحة لا يوجد رأس retry-after، وقد يستمر الفشل حتى استعادة الوصول.
كما قد تظهر حدود تسارع عند ارتفاع الاستخدام فجأة. زد الحركة تدريجيًا، ولا تعامل كل429 كإشارة لإعادة الطلب فورًا إلى ما لا نهاية.
أخطاء الخدمة والمهلة
يدل500على خطأ داخلي،و504على انتهاء مهلة المعالجة،و529على ضغط مؤقت في الخدمة. يعيدSDKالرسمي محاولة بعض الأعطال العابرة بتأخير أُسّي مرتين افتراضيًا، مع مراعاة retry-after عند وجوده؛ فتحقق من إعداداته قبل إضافة طبقة إعادة أخرى.
نجاح HTTP لا يضمن اكتمال البث
قد يبدأ بثSSEباستجابة200ثم يقع خطأ أثناءه. لذلك افحص نهاية البث وأحداث الخطأ، ولا تحفظ جزءًا من النص على أنه نتيجة مكتملة لمجرد نجاح الاتصال الأولي.
معرف الطلب للتتبع
احفظ رأس request-id عند توفره؛ويظهر المعرف أيضًا في حقل request_id بجسم استجابة الخطأ. وميز بينه وبين نص الرسالة ونوع الخطأ، فهو ما يساعد الدعم على تتبع طلب محدد دون مشاركة بيانات مصادقتك.
