MCP রেট লিমিট ও ত্রুটি কোড

রেট লিমিট

দুটি স্তর। কোনো অ্যাকাউন্ট বা কী লাগে না: কী ছাড়া আপনি কী-বিহীন স্তরে থাকেন; একটি বিনামূল্যের কী (শুরু করার গাইড) আপনাকে কী-সহ স্তরে নেয়।

	কী ছাড়া	বিনামূল্যের কী সহ
টুল কল	প্রতি IP ঠিকানায় মিনিটে ১০ ও দিনে ২০০	প্রতি কী-তে মিনিটে ৬০ রিকোয়েস্ট
সংযোগ ও টুল তালিকা	বিনামূল্যে; প্রতি IP-তে মিনিটে ৬০-এর বন্যা-সীমা	৬০-এর মধ্যে গণনা হয়
shamela_get_pages_range	প্রতি কলে সর্বোচ্চ ৫ পৃষ্ঠা	সর্বোচ্চ ২০
shamela_get_book_section	প্রতি কলে সর্বোচ্চ ১০ পৃষ্ঠা	সর্বোচ্চ ১০০

সব উইন্ডো স্লাইডিং। প্রত্যাখ্যাত কল কিছু খরচ করে না — মিনিটের সীমায় পৌঁছালে দৈনিক সীমা কমে না।

কী-বিহীন সীমা প্রতি IP ঠিকানায় গণনা করা হয়, কারণ গণনার মতো আর কিছু নেই। সব কী-বিহীন কলকারী একটি সাধারণ সক্ষমতার পুল ভাগ করে, তাই ব্যস্ত সময়ে নিজের সীমায় পৌঁছানোর আগেই কী-বিহীন কল প্রত্যাখ্যাত হতে পারে; ত্রুটির বার্তা সেটি জানায়। ছোট পৃষ্ঠা-পরিসর মানে হারানো পৃষ্ঠা নয়: উত্তর বলে দেয় কোথা থেকে চালিয়ে যেতে হবে।

কী-সহ সীমা গণনা হয় কী-এর বিপরীতে, আপনার IP ঠিকানার নয়। MCP ক্লায়েন্ট প্রায়ই শেয়ার্ড নেটওয়ার্কের পেছনে থাকে, এবং প্রতিটি সার্চ একটি শেয়ার্ড লাইব্রেরি সার্ভিসের বিপরীতে চলে, তাই রিকোয়েস্ট যেখান থেকেই আসুক, খরচ বাস্তব।

প্রতিটি রেসপন্সে বর্তমান অবস্থা থাকে:

হেডার	অর্থ
ratelimit-limit	যে সীমাটি পৌঁছানোর সবচেয়ে কাছাকাছি।
ratelimit-remaining	সেই সীমার অধীনে অবশিষ্ট রিকোয়েস্ট।
ratelimit-reset	তার উইন্ডো রিসেট হতে কত সেকেন্ড।

সীমা ছাড়ালে আপনি 429 পান, একটি retry-after হেডার এবং কোন সীমায় পৌঁছেছেন তা বলে দেওয়া একটি বার্তাসহ। ততক্ষণ অপেক্ষা করে আবার শুরু করুন — অথবা বার্তাটি কী-বিহীন স্তর সম্পর্কে হলে একটি কী যোগ করুন।

একটি search_library কল আপনার সীমার বিপরীতে একটি রিকোয়েস্ট, যদিও এটি ভেতরে দুটি পাস চালাতে পারে।

যে চারটি ত্রুটি সামলাতে হবে

কী না থাকার কারণে কোনো রিকোয়েস্ট কখনো প্রত্যাখ্যাত হয় না। যে কী পাঠানো হয় সেটি যাচাই করা হয়, এবং ভুল কী নীরবে কী-বিহীন হিসেবে গণ্য না করে প্রত্যাখ্যান করা হয় — নইলে আপনি কখনো জানতেই পারতেন না যে সেটি কাজ করা বন্ধ করেছে।

প্রতিটি ত্রুটির বডি id: null সহ একটি JSON-RPC ত্রুটি, তাই স্ট্যাটাস লুকানো থাকলেও কোডটি বলে দেয় আপনি কোন ক্ষেত্রে পড়েছেন।

স্ট্যাটাস	JSON-RPC কোড	অর্থ	কী করবেন
401	-32001	একটি কী পাঠানো হয়েছে এবং তা বৈধ নয়।	Authorization: Bearer … হেডার পরীক্ষা করুন। কী মুছে গেলে নতুন একটি তৈরি করুন — অথবা কী-বিহীন স্তরে চালিয়ে যেতে হেডারটি সরিয়ে দিন।
403	-32003	কী বৈধ কিন্তু সার্ভার ব্যবহার করতে পারে না: তার অ্যাকাউন্ট স্থগিত।	দেখুন নিষিদ্ধ অ্যাকাউন্ট।
429	-32004	একটি রেট লিমিটে পৌঁছেছে; বার্তা বলে কোনটি। Retry-After হেডার বলে কত সেকেন্ড অপেক্ষা করতে হবে।	অপেক্ষা করে আবার চেষ্টা করুন। কী-বিহীন ব্যবহারকারীরা একটি বিনামূল্যের কীও যোগ করতে পারেন।
503	-32002	আপনার কী এই মুহূর্তে যাচাই করা যায়নি, তাই রিকোয়েস্ট ছেড়ে না দিয়ে প্রত্যাখ্যান করা হয়েছে।	ক্ষণস্থায়ী। Retry-After হেডারের (৩০ সেকেন্ড) পর আবার চেষ্টা করুন।

একটি 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 নয়।

এ কারণেই যে ক্লায়েন্ট হঠাৎ শূন্য টুল তালিকাভুক্ত করে, সে আপনাকে একটি আসল সংকেত দেখাচ্ছে, কনফিগারেশন সমস্যা নয়। এক মিনিট সময় দিয়ে আবার সংযুক্ত হোন।

কী হারালে

কী পুনরুদ্ধার করা যায় না — কেবল একটি হ্যাশ সংরক্ষিত থাকে। হারিয়ে গেলে বা ফাঁস হয়েছে মনে হলে, আগে সেটি মুছুন, তারপর একটি বিকল্প তৈরি করুন। আগে মোছা সেই সময়-ফাঁক বন্ধ করে, যখন অন্য কারো কাছে একটি কার্যকর কী থাকে।

বাতিল এই এন্ডপয়েন্টে পৌঁছাতে ৬০ সেকেন্ড পর্যন্ত লাগে। যাচাইকৃত কী এক মিনিট ক্যাশ করা হয়, যাতে প্রতিটি টুল কলে অ্যাকাউন্ট সার্ভিসে যেতে না হয়। যে কী এইমাত্র মুছেছেন তা সেই মিনিট শেষ না হওয়া পর্যন্ত কাজ করতে থাকতে পারে — বাস্তবে প্রায় ৬ সেকেন্ড মাপা হয়েছে, কিন্তু ৬০ ধরে পরিকল্পনা করুন।

ফাঁস হওয়া কী বাতিল করার সময়, গুছিয়ে রাখার সময় নয়, এই সময়-ফাঁক গুরুত্বপূর্ণ। তবুও সঙ্গে সঙ্গে মুছুন; তারপর পরের মিনিটকে এখনো উন্মুক্ত ধরুন, এমন ভাববেন না যে ক্লিক করার মুহূর্তেই দরজা বন্ধ হয়ে গেছে।

কী পরিচালনার পূর্ণ বিবরণ API কী-তে আছে।