نجاح طلب Claude API من ناحية الاتصال لا يعني أن النص الناتج مكتمل أو صالح للاعتماد. الحقل stop_reason يوضح سبب توقف التوليد، وقد يتطلب استمرارًا أو معالجة مختلفة بدل إظهار الإجابة فورًا. هذا دليل تجهيز لتطبيقات 2027 وفق الوثائق المتاحة في 27 أكتوبر 2026.
النهاية الطبيعية ليست فحص جودة
تشير end_turn إلى انتهاء رد المساعد بصورة طبيعية، ولا تثبت صحة المعلومات أو استيفاء كل متطلبات التطبيق. افحص وجود المحتوى وشكله، ثم طبق اختباراتك المعتادة قبل عرضه أو حفظه.
قد يصل رد فارغ بهذه النهاية، خصوصًا بعد نتائج الأدوات أو عند إعادة الرد المكتمل دون إضافة شيء. لا تعالج ذلك بإعادة الرد الفارغ كما هو مرارًا؛ راجع بنية الرسائل أولًا، واجعل طلب الاستمرار في رسالة مستخدم جديدة حلًا لاحقًا إذا لم تعالج إصلاحات البنية المشكلة.
حد التوليد يختلف عن امتلاء السياق
تعني max_tokens بلوغ حد الرموز المحدد في الطلب. لا تعتبر فقرة أخيرة سليمة لغويًا دليلًا على اكتمال المخرج؛ ارفع الحد أو أكمل الرد بحسب الحالة.
وإذا قطع الحد كتلة استدعاء أداة قبل اكتمالها، أعد الطلب بحد أعلى للحصول على الاستدعاء الكامل بدل تنفيذ بيانات ناقصة. أما model_context_window_exceeded فيعني بلوغ نافذة السياق، ويجب التعامل مع الاستجابة على أنها مبتورة، لا نهاية طبيعية.
التوقف الذي حدده تطبيقك
تظهر stop_sequence عند مواجهة إحدى سلاسل الإيقاف المخصصة في الطلب. اقرأ حقل stop_sequence نفسه لمعرفة السلسلة التي طابقت، ثم تحقق أن هذا هو الموضع الذي أردت إيقاف النص عنده.
لا تساوِ بين التوقف المخصص وبلوغ حد التوليد؛ فلكل منهما سبب مختلف، وتسجيل السبب والسلسلة يساعد على اكتشاف توقف مبكر سببه إعداد التطبيق لا طول الجواب.
طلب الأداة أو استراحة الدور
في tool_use يكون هناك استدعاء أداة يحتاج إلى المعالجة، لا جواب نهائي جاهز. وتختلف pause_turn التي قد تنشأ عند حد تكرارات أدوات الخادم؛ لاستكمالها يعاد محتوى رد المساعد كما هو ضمن المحادثة.
لا ترسل نتائج أدوات العميل وكأنها استمرار لأداة خادم، ولا تنشئ حلقة إعادة غير محدودة لمجرد أن الرد لم يحمل جوابًا نصيًا نهائيًا.
الرفض ليس خطأ اتصال
قد تصل refusal ضمن استجابة HTTP 200. لذلك لن ترصدها مراقبة أخطاء الاتصال وحدها. افحص stop_details، واعرض رسالة مناسبة بدل اعتماد النص الجزئي كإجابة مكتملة.
وفي البث، يصل سبب التوقف وتفاصيل الرفض في حدث message_delta. قد تكون حقول الفئة والشرح داخل تفاصيل الرفض فارغة؛ لا تبن منطق التطبيق على افتراض وجود نص فيهما دائمًا.
