قراءة الأخطاء في سلك الاتصال

لا تنجح كل الطلبات. فعندما يحدث خطأ، يعيد JSON-RPC كائن error بدلًا من النتيجة، وقراءته هي أسرع طريق لإصلاح المشكلة.

يحتفظ رد الخطأ بمعرّف الطلب id، لكنه يستبدل result بكائن خطأ يحتوي على رمز ورسالة.

يحمل كل خطأ رمزًا رقميًا code. وتكون رموز JSON-RPC القياسية أرقامًا سالبة، ويتكرر ظهور عدد قليل منها على السلك.

يعني الرمز -32700 أن الخادم لم يتمكن حتى من تحليل JSON. وعادةً ما تكون فاصلة زائدة أو علامة اقتباس غير صحيحة قد أفسدت الرسالة نفسها.

يشير الرمز -32601 إلى أن اسم الطريقة غير موجود. تحقّق من وجود خطأ إملائي أو من أنك تستخدم طريقة لم يعلن عنها الخادم، مثل toolz/list.

يشير الرمز -32602 إلى وجود معلمات غير صحيحة: وسيطة مفقودة أو نوع غير صحيح. الطريقة موجودة، لكن المدخلات التي أرسلتها لا تتوافق معها.

الرمز -32603 هو الخطأ الداخلي العام للخادم. كان الطلب سليمًا، لكن حدثت مشكلة ما أثناء معالجته.

يخبرك الرمز بالفئة، بينما تروي لك message التفاصيل. احرص دائمًا على قراءتها، إذ تضيف الخوادم غالبًا اسم الحقل أو السبب المحدد للفشل.

قد تحتوي الأخطاء أيضًا على حقل data يتضمن تفاصيل منظمة إضافية، مثل المعلَمة التي رُفضت. وهذا مفيد جدًا لتصحيح الأخطاء عند توفره.

يعني error في JSON-RPC أن البروتوكول نفسه فشل. أما الأداة التي تعمل ثم تعيد isError فتبقى نتيجة عادية، لذا لا تخلط بين الحالتين.

كوّن هذه العادة: اقرأ code لتصنيف الخطأ، واقرأ الرسالة لتحديد موضعه، ثم افحص data لمعرفة السبب الدقيق. بهذه الطريقة تُكتشف معظم أخطاء MCP سريعًا.

أرسلت طريقة صالحة، لكن مع وسيطة مفقودة. ما رمز الخطأ المناسب؟

يمكنك الآن قراءة حالات الفشل بسهولة: يحتوي كائن error على code وmessage وأحيانًا data. يصنّف code الخطأ، وتشرحه message، وتحدد data سببه بدقة.