تخطَّ إلى المحتوى

حدود الاستخدام وأكواد الأخطاء في خادم MCP

حدود الاستخدام بلا مفتاح: 10 طلبات في الدقيقة و200 في اليوم لكل IP، و60 في الدقيقة بمفتاح مجاني، وأخطاء 401 و403 و429 و503.

في هذه الصفحة

حدود الاستخدام

مستويان. لا حاجة إلى حساب ولا مفتاح: فبلا مفتاح أنت في المستوى بلا مفتاح؛ ومفتاح مجاني (البدء) ينقلك إلى المستوى ذي المفتاح.

بلا مفتاحبمفتاح مجاني
استدعاءات الأدوات10 في الدقيقة و200 في اليوم لكل عنوان IP60 طلبًا في الدقيقة لكل مفتاح
الاتصال وسرد الأدواتمجاني؛ وسقف حماية من الفيض 60 في الدقيقة لكل IPيُحتسب ضمن الـ60
shamela_read (unit: 'range')حتى 5 صفحات في الاستدعاءحتى 20
shamela_read (unit: 'section')حتى 10 صفحات في الاستدعاءحتى 100

كل النوافذ منزلقة. والاستدعاء المرفوض لا يستهلك شيئًا — فبلوغ حد الدقيقة لا يُنقص من الحد اليومي.

تُحتسب حدود الاستخدام بلا مفتاح لكل عنوان IP، إذ لا شيء آخر يُحتسب عليه. ويشترك كل من يستعمل بلا مفتاح في مجمّع طاقة واحد، فقد يُرفض استدعاؤك في وقت الذروة قبل بلوغ حدك الخاص؛ وتذكر رسالة الخطأ ذلك. وقصر نطاق الصفحات لا يضيّع صفحة: فالرد يبيّن من أين تُكمل.

وتُحتسب حدود المفتاح على المفتاح لا على عنوان IP. فعملاء MCP كثيرًا ما يكونون خلف شبكات مشتركة، وكل بحث يجري على خدمة مكتبة مشتركة، فالكلفة حقيقية أيًّا كان مصدر الطلب.

يحمل كل رد الحالة الراهنة:

الترويسةمعناها
ratelimit-limitالسقف الأقرب إلى البلوغ.
ratelimit-remainingالطلبات المتبقية تحت ذلك السقف.
ratelimit-resetالثواني حتى تُعاد نافذته.

وإذا تجاوزت حدًّا نلتَ 429 مع ترويسة retry-after ورسالة تسمّي الحد الذي بلغته. انتظر تلك المدة ثم تابع — أو أضف مفتاحًا إن كانت الرسالة عن المستوى بلا مفتاح.

استدعاء shamela_search_library واحد يُحتسب طلبًا واحدًا على حدك، وإن جرى داخليًا على مرحلتين.

الأخطاء الأربعة التي ينبغي معالجتها

لا يُرفض طلب بلا مفتاح لغياب المفتاح. أما المفتاح المُرسَل فيُفحص، والمفتاح الخاطئ يُرفض ولا يُعامل بصمت على أنه بلا مفتاح — وإلا لما علمتَ أنه توقف عن العمل.

كل جسم خطأ هو خطأ JSON-RPC مع id: null، فيدلّك الكود على الحالة حتى لو خُفيت حالة HTTP.

الحالةكود JSON-RPCالمعنىما العمل
401-32001أُرسل مفتاح وهو غير صالح.تحقق من ترويسة Authorization: Bearer …. فإن حُذف المفتاح فأنشئ آخر — أو أزل الترويسة لتتابع في المستوى بلا مفتاح.
403-32003المفتاح صالح لكن لا يحق له استعمال الخادم: حسابه موقوف.انظر الحسابات المحظورة.
429-32004بلغتَ حد الاستخدام؛ وتذكر الرسالة أيّها. وتبيّن ترويسة Retry-After كم ثانية تنتظر.انتظر ثم أعد المحاولة. ويستطيع من يستعمل بلا مفتاح أن يضيف مفتاحًا مجانيًا.
503-32002تعذّر التحقق من مفتاحك الآن، فرُفض الطلب بدل أن يُمرَّر.عابر. أعد المحاولة بعد ترويسة Retry-After (30 ثانية).

يعني 503 أن الخادم لم يستطع التأكد من صلاحية مفتاحك، فرفض الطلب بدل أن يخمّن. ولا يقبل أبدًا مفتاحًا لا يمكن التحقق منه — فالطلب الذي لا تمكن مصادقته يُرفض ولا يُمرَّر.

الطلبات المشوّهة وأعطال الخادم

وسوى هذه الأربعة لا يرسل الخادم إلا هذه، وهي لا يثيرها عميل MCP عادي:

الحالةكود JSON-RPCالمعنىما العمل
400-32700الجسم ليس JSON صالحًا.أصلح الطلب؛ فإعادته كما هو تفشل بالطريقة نفسها.
400-32600الجسم JSON لكنه ليس طلب JSON-RPC 2.0 (يفتقد jsonrpc: "2.0" أو method، أو هو دفعة).أرسل طلبًا واحدًا في كل POST — فـMCP 2025-06-18 لا تدعم الدفعات.
500-32603عطل غير متوقع في الخادم.أعد المحاولة مرة واحدة بعد ثوانٍ؛ فإن استمر فالعطل من جهتنا.

ولا يصدر 502 أو 504 عن خادم MCP — بل عن الوسيط أمامه حين يُعاد تشغيل الخادم أو يتعذر الوصول إليه. عامله كـ500 وأعد المحاولة بعد قليل.

نوعان من الإخفاق

بعد أن تُصادَق، تصلك الإخفاقات بإحدى صورتين، والفرق مقصود.

خطأ الأداة يعود نتيجةً عادية موسومة بـisError، مع رسالة يستطيع مساعدك قراءتها والتصرف بها. أرسل نطاقًا غير صالح تتلقَّ قائمة النطاقات الصالحة، ليعيد النموذج المحاولة بنطاق حقيقي:

scope is required and must be one of: hadith-primary, tafsir-canonical, fiqh-hanafi, …

وخطأ البروتوكول يعود خطأ JSON-RPC، للمشكلات التي لا يستطيع مساعدك إصلاحها بإعادة المحاولة — كطلب أداة غير موجودة، أو إرسال طلب مشوّه.

الحالةالصورة
scope مفقود أو غير صالحخطأ أداة (isError)
query فارغخطأ أداة (isError)
تنقطع المكتبة أثناء الاستدعاءخطأ أداة (isError)
المكتبة متعذّرة أصلًا حين تستدعيخطأ بروتوكول -32601 (انظر أدناه)
اسم أداة مجهولخطأ بروتوكول -32601
طلب JSON-RPC مشوّهخطأ بروتوكول -32600

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

عند تعذّر المكتبة

إن تعذّر الوصول إلى خدمة المكتبة فإن tools/list تعيد صفر أدوات بدل الإعلان عن أداة ستفشل في منتصف الاستدعاء، وأي استدعاء يُحاول يعيد خطأ بروتوكول -32601 برسالة تقول إن المكتبة متعذّرة الوصول مؤقتًا. هذا HTTP 200 وليس 503.

ولهذا فإن عميلًا يعرض فجأة صفر أدوات يُريك إشارة حقيقية لا مشكلة إعداد. امنحه دقيقة ثم أعد الاتصال.

فقدان مفتاح

لا يمكن استرجاع المفاتيح — إذ لا يُخزَّن إلا تجزئتها (hash). فإن فقدتَ مفتاحًا أو ظننت أنه تسرّب فـاحذفه أولًا ثم أنشئ بديلًا. فالحذف أولًا يغلق الفترة التي قد يحمل فيها غيرك مفتاحًا يعمل.

يستغرق سريان الإبطال حتى 60 ثانية على هذه النقطة. تُخزَّن المفاتيح الموثّقة مؤقتًا دقيقة كي لا يحتاج كل استدعاء أداة إلى رحلة إلى خدمة الحسابات. وقد يظل مفتاح حذفته للتوّ يعمل حتى تنتهي تلك الدقيقة — قيس نحو 6 ثوانٍ عمليًا، لكن خطّط على 60.

وتهمّ هذه الفترة حين تُبطل مفتاحًا مسرَّبًا لا حين تنظّف فحسب. احذفه فورًا على أي حال؛ ثم عدّ الدقيقة التالية ما زالت مكشوفة، ولا تفترض أن الباب أُغلق لحظة نقرتك.

وإدارة المفاتيح كاملةً في مفاتيح API.

الخطوات التالية

عدّل هذه الصفحة على GitHub