MCP کی ریٹ لمٹس اور غلطی کے کوڈز
بغیر کلید فی IP فی منٹ 10 اور روزانہ 200 درخواستیں، مفت کلید کے ساتھ فی منٹ 60، اور 401، 403، 429 اور 503 غلطیاں جو آپ کو مل سکتی ہیں۔
اس صفحے پر
ریٹ لمٹس
دو درجے۔ اکاؤنٹ یا کلید درکار نہیں: کلید کے بغیر آپ بغیر کلید والے درجے پر ہیں؛ ایک مفت کلید (شروعات) آپ کو کلید والے درجے پر لے جاتی ہے۔
| بغیر کلید | مفت کلید کے ساتھ | |
|---|---|---|
| ٹول کالز | فی منٹ 10 اور روزانہ 200، فی IP ایڈریس | فی منٹ 60 درخواستیں، فی کلید |
| کنیکٹ کرنا اور ٹولز کی فہرست | مفت؛ سیلاب کی بالائی حد فی IP فی منٹ 60 | 60 میں شمار ہوتی ہے |
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 میں ہے۔