مواد پر جائیں

MCP کی ریٹ لمٹس اور غلطی کے کوڈز

بغیر کلید فی IP فی منٹ 10 اور روزانہ 200 درخواستیں، مفت کلید کے ساتھ فی منٹ 60، اور 401، 403، 429 اور 503 غلطیاں جو آپ کو مل سکتی ہیں۔

اس صفحے پر

ریٹ لمٹس

دو درجے۔ اکاؤنٹ یا کلید درکار نہیں: کلید کے بغیر آپ بغیر کلید والے درجے پر ہیں؛ ایک مفت کلید (شروعات) آپ کو کلید والے درجے پر لے جاتی ہے۔

بغیر کلیدمفت کلید کے ساتھ
ٹول کالزفی منٹ 10 اور روزانہ 200، فی IP ایڈریسفی منٹ 60 درخواستیں، فی کلید
کنیکٹ کرنا اور ٹولز کی فہرستمفت؛ سیلاب کی بالائی حد فی IP فی منٹ 6060 میں شمار ہوتی ہے
shamela_read (unit: 'range')فی کال 5 صفحات تک20 تک
shamela_read (unit: 'section')فی کال 10 صفحات تک100 تک

تمام کھڑکیاں سلائیڈنگ ہیں۔ مسترد کی گئی کال کچھ خرچ نہیں کرتی — فی منٹ کی حد تک پہنچنا روزانہ کی حد میں سے نہیں کاٹتا۔

بغیر کلید والی حدیں فی IP ایڈریس گنی جاتی ہیں، کیونکہ گننے کے لیے اور کچھ نہیں۔ بغیر کلید والے تمام کال کرنے والے گنجائش کا ایک ہی ذخیرہ بھی بانٹتے ہیں، اس لیے مصروف لمحے میں بغیر کلید والی کال آپ کی اپنی حد تک پہنچنے سے پہلے مسترد ہو سکتی ہے؛ غلطی کا پیغام یہی بتاتا ہے۔ چھوٹی صفحاتی حد کا مطلب کھویا ہوا صفحہ نہیں: جواب بتاتا ہے کہ آگے کہاں سے جاری رکھنا ہے۔

کلید والی حدیں کلید کے مقابل گنی جاتی ہیں، آپ کے IP ایڈریس کے نہیں۔ MCP کلائنٹس اکثر مشترکہ نیٹ ورکس کے پیچھے ہوتے ہیں، اور ہر تلاش ایک مشترکہ لائبریری سروس پر چلتی ہے، اس لیے لاگت حقیقی ہے خواہ درخواست کہیں سے آئی ہو۔

ہر جواب موجودہ حالت لے کر آتا ہے:

ہیڈرمطلب
ratelimit-limitوہ بالائی حد جو پہنچنے کے سب سے قریب ہے۔
ratelimit-remainingاس حد کے تحت باقی درخواستیں۔
ratelimit-resetاس کی کھڑکی ری سیٹ ہونے تک کے سیکنڈ۔

کوئی حد پار کریں تو آپ کو retry-after ہیڈر کے ساتھ 429 ملتا ہے اور پیغام بتاتا ہے کہ آپ کون سی حد تک پہنچے۔ اتنی دیر انتظار کریں اور دوبارہ شروع کریں — یا، اگر پیغام بغیر کلید والے درجے کے بارے میں ہو تو کلید شامل کریں۔

ایک shamela_search_library کال آپ کی حد کے مقابل ایک درخواست ہے، حالانکہ وہ اندرونی طور پر دو مراحل چلا سکتی ہے۔

چار غلطیاں جنہیں سنبھالنا ہے

کلید نہ ہونے پر کوئی درخواست کبھی مسترد نہیں ہوتی۔ جو کلید بھیجی جائے اس کی جانچ ہوتی ہے، اور بری کلید کو خاموشی سے بغیر کلید کے سمجھنے کے بجائے مسترد کر دیا جاتا ہے — ورنہ آپ کو کبھی پتا نہ چلتا کہ وہ کام کرنا چھوڑ چکی ہے۔

ہر غلطی کی باڈی id: null کے ساتھ JSON-RPC غلطی ہے، اس لیے کوڈ بتاتا ہے کہ آپ کس صورت سے دوچار ہوئے خواہ اسٹیٹس چھپا ہو۔

اسٹیٹس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 غائب، یا batch)۔ہر POST میں ایک درخواست بھیجیں — MCP 2025-06-18 میں batching نہیں ہے۔
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 نہیں۔

اسی لیے وہ کلائنٹ جو اچانک صفر ٹولز دکھائے آپ کو ایک حقیقی اشارہ دکھا رہا ہے، کنفیگریشن کا مسئلہ نہیں۔ اسے ایک منٹ دیں اور دوبارہ کنیکٹ کریں۔

کلید کھو جانا

کلیدیں بازیافت نہیں ہو سکتیں — صرف ایک ہیش محفوظ ہوتا ہے۔ اگر آپ کی کھو جائے یا آپ کو لگے کہ لیک ہو گئی ہے تو پہلے اسے حذف کریں، پھر متبادل بنائیں۔ پہلے حذف کرنے سے وہ کھڑکی بند ہو جاتی ہے جس میں کسی اور کے پاس کام کرنے والی کلید ہو۔

منسوخی کو اس اینڈ پوائنٹ تک پہنچنے میں 60 سیکنڈ تک لگ سکتے ہیں۔ تصدیق شدہ کلیدیں ایک منٹ کے لیے کیش کی جاتی ہیں تاکہ ہر ٹول کال کو اکاؤنٹس سروس تک چکر نہ لگانا پڑے۔ جو کلید آپ نے ابھی حذف کی وہ اس منٹ کے ختم ہونے تک کام کرتی رہ سکتی ہے — عملاً تقریباً 6 سیکنڈ ناپا گیا، مگر 60 کا حساب رکھیں۔

یہ کھڑکی تب اہم ہے جب آپ کسی لیک شدہ کلید کو منسوخ کر رہے ہوں، صفائی نہیں۔ پھر بھی اسے فوراً حذف کریں؛ پھر اگلے منٹ کو یہ مانے بغیر کہ دروازہ کلک کرتے ہی بند ہو گیا، اب بھی بے نقاب سمجھیں۔

کلیدوں کا مکمل انتظام API keys میں ہے۔

اگلے مراحل

اس صفحے کو GitHub پر ایڈٹ کریں