Notion MCP Rate Limit: Claude से कनेक्ट करें और एरर ठीक करें

आप Claude से Notion में चालीस मीटिंग नोट्स सुव्यवस्थित करने को कहते हैं, और बीच में वह एक rate limit वाले संदेश के साथ रुक जाता है। कुछ टूटा नहीं है। Notion वही कर रहा है जो हर व्यस्त सर्विस करती है, जब अनुरोध उससे तेज़ी से आने लगें जितनी तेज़ी से वह उन्हें पूरा करना चाहती है: वह कहती है "रुकिए," और एक शिष्ट क्लाइंट रुक जाता है। दिक्कत यह है कि AI असिस्टेंट हमेशा शिष्ट नहीं होता। वह एक सर्च चला सकता है, नतीजे पढ़ सकता है, छह और सर्च चला सकता है, और कुछ सेकंड में पूरे एक मिनट का बजट खर्च कर सकता है।

यह लेख Notion MCP rate limit को दोनों तरफ़ से समझाता है। आप देखेंगे कि Notion को Claude से कैसे कनेक्ट करें, सीमाएँ असल में क्या अनुमति देती हैं, error आने पर उसे कैसे पढ़ें, और कौन-सी आदतें उसे दोबारा आने से रोकती हैं। नीचे के आँकड़े Notion के अपने developer documentation से लिए गए हैं, इसलिए आप इनमें से हर एक की जाँच कर सकते हैं।

💡 त्वरित उत्तर: Notion का होस्टेड MCP सर्वर https://mcp.notion.com/mcp पर उपलब्ध है। Notion की API सीमाएँ उसके टूल्स पर लागू होती हैं: ज़्यादातर प्लान पर प्रति मिनट 180 requests, Business और Enterprise पर 600, और search व data source queries पर एक सख्त सीमा, हर 10 सेकंड में 20 calls। जब 429 आए, तो Retry-After समय तक रुकें, फिर कम और बड़े requests भेजें।

Notion MCP Rate Limit का मतलब क्या है

Rate limit एक नल की तरह काम करता है, दीवार की तरह नहीं। Notion हर कनेक्शन को प्रति मिनट एक तय मात्रा में पानी देता है। आप वाल्व पूरा खोलकर सारा पानी एक बार में खर्च कर सकते हैं, या उसे धीरे-धीरे टपकने दे सकते हैं। जब कप खाली हो जाता है, तो विंडो रीसेट होने तक नल बंद हो जाता है। Model Context Protocol (MCP) इस नियम को नहीं बदलता। वह केवल यह बदलता है कि नल किसके हाथ में है। MCP के साथ नल उस AI मॉडल के हाथ में होता है, जो खुद तय करता है कि कितनी calls करनी हैं।

429 के पीछे के आँकड़े

ये वे सीमाएँ हैं जो मायने रखती हैं, जो Notion के request limits पेज और उसके supported tools पेज से ली गई हैं।

दो बातें आसानी से छूट जाती हैं। पहली, प्रति मिनट वाला बजट एक विंडो है, इसलिए पहले दस सेकंड में 180 calls का एक बर्स्ट अनुमति है, लेकिन 181वीं call तब तक इंतज़ार करेगी जब तक विंडो रीसेट न हो। दूसरी, search और query की सीमाएँ अलग हैं और कहीं ज़्यादा सख्त हैं। 10 सेकंड में 20 calls का मतलब है प्रति सेकंड दो, जो सामान्य बजट के प्रति सेकंड 3 के औसत से भी कम है। जो असिस्टेंट लूप में सर्च करता है, वह सामान्य सीमा तक पहुँचने से बहुत पहले इस सीमा पर पहुँच जाता है।

💡 टिप: Notion समय के साथ अपनी सीमाएँ बदलता रहता है। इस टेबल को एक स्नैपशॉट मानें, और ऐसी कोई चीज़ बनाने से पहले request limits पेज देख लें जो किसी सटीक संख्या पर निर्भर हो।

Claude इतनी जल्दी सीमा तक क्यों पहुँचता है

Claude की हर tool call एक request है। "Q3 लॉन्च के बारे में सब कुछ सारांशित करो" जैसा प्रॉम्प्ट एक ही काम लगता है, लेकिन वह एक चेन में फैल जाता है: एक notion-search, फिर उसके लौटाए पेजों के लिए कई notion-fetch calls, और फिर चाइल्ड पेजों और लिंक्ड डेटाबेस के लिए और fetches। Notion में क्लिक करते हुए इंसान हर कुछ सेकंड में एक request करता है। योजना के चरणों पर काम करता असिस्टेंट उन्हें लगातार, एक के बाद एक करता है।

आम कारण ये हैं:

• चौड़ी सर्च जो कई पेज लौटाती है, और फिर उनमें से हर एक को fetch किया जाता है
• डेटाबेस पर लूप, जैसे 50 rows को एक-एक करके एडिट करना
• तुरंत retries, जहाँ मॉडल बिना रुके नाकाम request दोहराता है
• Parallel tool calls, जहाँ कई requests एक ही सेकंड में निकल जाती हैं
• लंबी चैट जो बार-बार वही पेज दोबारा पढ़ती रहती हैं

Notion पहले झटके को कुछ हद तक सँभालता है। MCP सर्वर जब इंतज़ार दो सेकंड या उससे कम हो, तो एक call को खुद एक बार दोबारा भेजता है। इससे लंबा इंतज़ार होने पर error तुरंत लौट आता है, और वही error आपको चैट में दिखता है।

Notion को Claude से कनेक्ट करें

कनेक्ट करने में कुछ मिनट लगते हैं और इसमें OAuth इस्तेमाल होता है, इसलिए आपको किसी config फ़ाइल में कोई secret पेस्ट नहीं करना पड़ता। Notion अपने MCP सर्वर को Notion द्वारा होस्ट किया गया remote सर्वर बताता है, यानी मानक सेटअप के लिए कुछ इंस्टॉल करने की ज़रूरत नहीं है।

Claude.ai Connector सेट करें

1. अपने ब्राउज़र या डेस्कटॉप ऐप में Claude खोलें और Settings में जाकर Connectors चुनें।
2. कनेक्टर डायरेक्टरी में Notion ढूँढें और Connect चुनें।
3. OAuth विंडो खुलने पर Notion में साइन इन करें और वह वर्कस्पेस चुनें जिस तक आप Claude को पहुँचने देना चाहते हैं।
4. कंसेंट स्क्रीन पर Notion जिन एक्सेस की सूची दिखाता है, उन्हें मंज़ूरी दें।
5. नई चैट शुरू करें, Notion कनेक्टर को ऑन करें और यह पक्का करने के लिए कि सब ठीक काम कर रहा है, Claude से किसी पेज को उसके नाम से ढूँढने को कहें।

💡 टिप: Anthropic के ऐप अपडेट होने पर मेन्यू के नाम बदल जाते हैं। अगर आपको Connectors न मिले, तो Settings के अंदर integrations या tools वाला हिस्सा देखें।

Claude Code में जोड़ें

Claude Code में एक ही command चाहिए। Notion का documentation Streamable HTTP address की सिफ़ारिश करता है:

claude mcp add --transport http notion https://mcp.notion.com/mcp

प्रॉम्प्ट कॉपी करें

इसके बाद Claude Code के अंदर /mcp चलाएँ और अपने ब्राउज़र में OAuth flow पूरा करें। Notion बताता है कि अभी कोई non-interactive authorization मौजूद नहीं है, इसलिए headless सर्वर साइन-इन खुद पूरा नहीं कर सकता। Scope flag तय करता है कि कनेक्शन किसे मिलेगा:

Remote support के बिना clients

कुछ clients remote सर्वर से सीधे बात नहीं कर सकते। उनके लिए Notion mcp-remote bridge की ओर इशारा करता है, जिसमें STDIO configuration है। https://mcp.notion.com/sse पर एक fallback SSE address भी है, लेकिन Streamable HTTP address ही सिफ़ारिश किया गया है। Notion अपने पुराने open-source सर्वर को deprecated भी बताता है और उसका सक्रिय रखरखाव नहीं करता, इसलिए नए सेटअप को होस्टेड सर्वर पर ही रखें। अगर कभी कनेक्शन authenticate न हो, तो उसे disconnect करें, फिर से connect करें, और जाँचें कि आपके Notion अकाउंट को workspace पर permission है।

ठीक करने से पहले error पढ़ें

"Rate limit" शब्द को उससे ज़्यादा दोष दिया जाता है जितना वह हकदार है। असली response पढ़ने से एक घंटे का अंदाज़ा लगाना बच जाता है।

rate_limited और Retry-After पहचानें

जब आप सीमा पार करते हैं, तो Notion का API HTTP status 429 और error code rate_limited लौटाता है। Response में पूरे सेकंड की संख्या वाला Retry-After header होता है, और जो clients headers नहीं पढ़ सकते, उनके लिए वही मान additional_data.retry_after में भी दोहराया जाता है।

MCP के ज़रिए वही विचार एक ज़्यादा आसान रूप में आता है। अगर इंतज़ार दो सेकंड या कम हो, तो सर्वर खुद एक बार दोबारा कोशिश करता है। अगर इंतज़ार लंबा हो, तो tool call तुरंत नाकाम होती है और retry_after_seconds और rate_limit_reason लौटाती है। Claude ये fields देखता है, और एक अच्छा प्रॉम्प्ट उसे बताता है कि इनके साथ क्या करना है।

Search और query throttles

Tool-विशिष्ट सीमाएँ वहीं हैं जहाँ ज़्यादातर असिस्टेंट लड़खड़ाते हैं। notion-search और notion-query-data-sources दोनों 10 सेकंड में 20 calls की अनुमति देते हैं। बार-बार सर्च करके सही पेज ढूँढता मॉडल यह सीमा पल भर में खर्च कर देता है, भले ही सामान्य प्रति मिनट बजट लगभग अछूता हो। जब आपको यह जानना हो कि कौन-सी सीमा ने call रोकी, तो सबसे पहले rate_limit_reason field देखें।

क्या यह सचमुच rate limit है?

कई समस्याएँ throttling जैसी दिखती हैं, पर होती नहीं हैं। कुछ भी बदलने से पहले लक्षण मिलाएँ।

Notion का limits पेज एक payload को 1,000 block elements और 500 KB तक सीमित करता है, और block types के arrays (rich text सहित) 100 elements तक सीमित हैं। किसी property में text content 2,000 characters पर जाकर रुक जाता है। बड़ा paste इन कारणों से नाकाम हो सकता है और पहली नज़र में throttle जैसा दिख सकता है।

Rate limit errors जल्दी ठीक करें

कम, बड़े requests भेजें

सबसे सस्ती request वह है जो आप कभी भेजते ही नहीं। चालीस rows को एक-एक करके एडिट करने के बजाय Claude से एक पेज के लिए पूरा बदलाव बनवाएँ और उसे एक notion-update-page call में लागू करें, इस बात का ध्यान रखते हुए कि 1,000 block और 500 KB की payload सीमा के भीतर रहें। एक call जो दस काम करती है, बजट के खिलाफ़ एक request गिनी जाती है।

व्यावहारिक तरीके:

• बदलाव समूहित करें पेज के हिसाब से, ताकि हर पेज एक बार छुआ जाए
• बड़े काम बाँटें चैट संदेश में 20 से 30 आइटम के batches में
• एक ही बार में कंटेंट बनाएँ notion-create-pages से, ब्लॉक एक-एक करके जोड़ने के बजाय

सर्च लूप को काबू में रखें

सर्च सबसे महँगी आदत है, क्योंकि हर सर्च के बाद fetches आते हैं। जब भी आपके पास सीधे addresses हों, Claude को वे दें। पेज का URL या ID उसे बिना किसी सर्च के सीधे notion-fetch call करने देता है। डेटाबेस के काम के लिए फ़िल्टर वाली notion-query-data-sources call एक ही बार में ज़रूरी rows लौटा देती है, जबकि बार-बार की सर्च टुकड़े लौटाती और 10 सेकंड में 20 calls की सीमा खर्च करती। जब सर्च ज़रूरी हो, तो एक सही दायरे वाली query माँगें। notion-search location, creator, date और status के फ़िल्टर सपोर्ट करता है, और एक संकरी query बाद में fetch करने के लिए कम पेज लौटाती है।

Retry storms रोकने वाले प्रॉम्प्ट

सबसे अच्छा समाधान कुछ खर्च नहीं करता: Claude को बताएँ कि Notion के मना करने पर उसे कैसे बर्ताव करना है। किसी बड़े काम की शुरुआत में ऐसा block पेस्ट करें:

Update the 30 pages in the "Meeting Notes" database one at a time.
Use notion-fetch with the page URL instead of searching for each page.
Run one Notion call at a time. If a call returns a rate limit error,
wait the number of seconds in retry_after_seconds, then continue from the same page.
After every 10 pages, tell me which pages are finished and which are left.

प्रॉम्प्ट कॉपी करें

आखिरी पंक्ति एक सुरक्षा जाल है। अगर चैट पेज 22 पर टूट जाए, तो आप ठीक जानते हैं कि कहाँ से फिर शुरू करना है, और उन्हीं पेजों के लिए दोबारा पैसे नहीं देने पड़ते।

कब अपग्रेड करें

Business और Enterprise कनेक्शनों को प्रति मिनट 600 requests मिलते हैं, जो बाकी प्लान के 180 से 3.3 गुना है। भारी automation में यह मदद करता है। Notion search और query की सीमाओं को अलग से सूचीबद्ध करता है, यानी 10 सेकंड में 20 calls, इसलिए बड़ा प्लान बजट इन्हें स्पष्ट रूप से नहीं बढ़ाता। पहले आदतें ठीक करें, फिर भी संख्याएँ फिट न बैठें तो अतिरिक्त क्षमता के लिए भुगतान करें। यह देखने के लिए कि आपके workspace प्लान पर कौन-से tools उपलब्ध हैं, notion-get-tool-access को कॉल करें।

पाँच गलतियाँ जो बजट जला देती हैं

1. एक ही प्रॉम्प्ट में "सब कुछ" माँगना, जो सैकड़ों fetches में फैल जाता है
2. Claude को तुरंत retry करने देना, बताए गए समय तक इंतज़ार करने के बजाय
3. उन पेजों को सर्च करना जिनका URL आपके पास पहले से है
4. कई भारी काम एक साथ चलाना, ताकि वे एक ही बजट के लिए होड़ करें
5. error का टेक्स्ट अनदेखा करना, और फिर वही प्रॉम्प्ट दोबारा भेजना

स्क्रिप्ट्स के लिए retry logic लिखें

अगर आप Claude के साथ-साथ अपनी स्क्रिप्ट्स से Notion को कॉल करते हैं, तो लय जल्दबाज़ी से बेहतर है। Notion की अपनी सलाह है कि retry logic को एक केंद्रीय जगह पर रखें, Retry-After का सम्मान करें, jitter के साथ exponential backoff इस्तेमाल करें, fallback देरी को 30 सेकंड पर सीमित करें, और कुल प्रयासों की संख्या सीमित करें।

Jitter के साथ backoff

import random
import time

import requests


def notion_request(method, url, headers, max_attempts=5, **kwargs):
    for attempt in range(max_attempts):
        response = requests.request(method, url, headers=headers, **kwargs)
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = int(retry_after)
        else:
            wait = min(2 ** attempt, 30)

        time.sleep(wait + random.uniform(0, 0.5))

    raise RuntimeError("Still rate limited after all attempts")

प्रॉम्प्ट कॉपी करें

Jitter मायने रखता है। उसके बिना दस workers जो एक साथ नाकाम हुए, वे एक साथ retry करेंगे और फिर एक साथ नाकाम होंगे। आधा सेकंड का एक random हिस्सा उन्हें फैला देता है।

Notion के docs की एक चेतावनी: अगर कोई write 503 लौटाए, तो उसे दोहराने से पहले additional_data.retry_guidance जाँचें, क्योंकि बदलाव शायद पहले ही सेव हो चुका हो। Writes पर अंधाधुंध retries duplicates बना सकते हैं।

नाकाम होने से पहले requests की गति तय करें

Backoff नाकामी पर प्रतिक्रिया देता है। Pacing उसे होने ही नहीं देती। Requests को समान रूप से फैलाएँ और बजट के लगभग 80 प्रतिशत के भीतर रहें:

Notion बर्स्ट की अनुमति देता है, इसलिए छोटे कामों के लिए pacing वैकल्पिक है। लंबे, बिना निगरानी वाले runs के लिए यही फ़र्क है कि काम सहजता से पूरा होता है या errors की दीवार खड़ी हो जाती है। Search और query calls को उनकी अपनी धीमी गति दें: लगभग हर 0.6 सेकंड में एक call आपको 10 सेकंड में 20 की सीमा से नीचे रखती है।

PicassoIA पर Claude Sonnet 5 इस्तेमाल करें

जब समस्या कोड की हो, तो एक coding मॉडल समय बचाता है। PicassoIA पर Claude Sonnet 5 error पढ़ता है, फिक्स लिखता है, और screenshots को input के रूप में स्वीकार करता है। साफ़ कह दें, यह आपके लिए स्क्रिप्ट्स और प्रॉम्प्ट बनाता है। यह अपने आप आपके Notion workspace से कनेक्ट नहीं होता।

1. PicassoIA पर Claude Sonnet 5 पेज खोलें।
2. कच्चा error Prompt में पेस्ट करें: 429 response, retry_after_seconds मान, और एक वाक्य कि आप क्या कर रहे थे।
3. Effort स्तर चुनें। डिफ़ॉल्ट, low, सबसे तेज़ जवाब देता है। कई फ़ाइलों को छूने वाली retry logic के लिए medium या high चुनें।
4. पूरे retry wrapper और व्याख्या के लिए Max Tokens को 8,192 पर रखें, या त्वरित जवाबों के लिए इसे कम करें।
5. System Prompt में कुछ ऐसा जोड़ें जैसे "आप एक सावधान backend engineer हैं। पहले कोड लिखें, फिर तीन लाइन की व्याख्या दें।"
6. अगर टेक्स्ट कॉपी करना मुश्किल हो, तो error का screenshot Image field में लगाएँ।
7. चलाएँ, नतीजा पढ़ें, और बड़े run से पहले कोड को एक छोटे batch पर टेस्ट करें।

कठिन, कई चरणों वाले coding कामों के लिए, Claude Fable 5 उसी Large Language Models संग्रह में है।

PicassoIA पर अपनी इमेज बनाएँ

एक बार आपका Notion workspace सुचारु चलने लगे, तो उसे बेहतर visuals दें। एक अच्छी header इमेज प्रोजेक्ट पेज, wiki के होम या लॉन्च brief को टेक्स्ट की दीवार से ऐसी चीज़ में बदल देती है जिसे लोग खोलना चाहें। PicassoIA Image और Seedream 5 Pro एक लाइन के प्रॉम्प्ट को फ़ोटोरियलिस्टिक तस्वीर में बदलते हैं, और हर नतीजा Notion पेज में डालने के लिए तैयार होता है।

इस आकार में एक प्रॉम्प्ट आज़माएँ: सब्जेक्ट, सेटिंग, रोशनी, लेंस। उदाहरण के लिए, "धूप वाली मेज़ पर छपे roadmaps देखता एक प्रोजेक्ट मैनेजर, नरम खिड़की की रोशनी, 50mm लेंस, प्राकृतिक film grain।" एक बार में एक ही चीज़ बदलें, और आप देखेंगे कि हर शब्द क्या करता है।

PicassoIA खोलें, एक मॉडल चुनें, और आज ही अपनी पहली header इमेज बनाएँ। उपलब्ध हर मॉडल picassoia.com/en/all-models पर देखें, और तब तक प्रयोग करते रहें जब तक आपके Notion पेज उतने ही अच्छे न दिखें जितने वे काम करते हैं।