रेट लिमिट और कोटा

दो तरह की सीमाएँ API को सभी के लिए तेज़ रखती हैं:

• कुंजी की रेट लिमिट: वह हर सेकंड कितनी रिक्वेस्ट भेज सकती है, छोटे उछाल के लिए बर्स्ट के साथ।
• संगठन के कोटा: उसकी सभी कुंजियाँ मिलाकर हर मिनट, हर दिन और हर महीने कितनी रिक्वेस्ट भेज सकती हैं।

दोनों संगठन के प्लान पर निर्भर करते हैं। हर रिस्पॉन्स बताता है कि आप कहाँ हैं, इसलिए सही ढंग से बना क्लाइंट कभी अंदाज़ा नहीं लगाता।

कुंजी की रेट लिमिट

हर कुंजी को एक स्थिर रफ़्तार और एक बर्स्ट मिलता है। बर्स्ट से आप उतनी रिक्वेस्ट एक साथ भेज सकते हैं; उसके बाद रिक्वेस्ट स्थिर रफ़्तार से स्वीकार की जाती हैं।

क्लास संगठन के प्लान से आती है। GET /v1/me उसे कॉल करने वाली कुंजी की क्लास, रफ़्तार और बर्स्ट दिखाता है (rate_limit)। सीमा पूरी कुंजी पर लागू होती है, चाहे आपकी रिक्वेस्ट कितने भी API सर्वर संभालें।

स्ट्रीमिंग एंडपॉइंट, POST /v1/chat ("stream": true के साथ या उसके बिना) और GET /v1/jobs/stream, कुंजी की रेट लिमिट से बाहर हैं: वे उसे इस्तेमाल नहीं करते, और उनके RateLimit हेडर में "key" आइटम नहीं होता। पर वे संगठन के कोटा में गिने जाते हैं, हर एक बार, रिक्वेस्ट शुरू होने पर। सवालों की अपनी सीमाएँ हैं, जिनका वर्णन नीचे है।

संगठन के कोटा

प्लान संगठन के लिए रिक्वेस्ट कोटा तय कर सकता है: हर मिनट, हर दिन और हर महीने के लिए। विंडो UTC में कैलेंडर अवधियाँ हैं: मिनट :00 सेकंड पर शुरू होता है, दिन 00:00 UTC पर, महीना पहले दिन 00:00 UTC पर। संगठन की कुंजी या OAuth टोकन वाली हर रिक्वेस्ट गिनी जाती है, किसी भी पते पर। स्ट्रीमिंग रिक्वेस्ट शुरू होने पर एक बार गिनी जाती है, चाहे वह कितनी भी देर चले; कोटा ख़त्म होने पर उसे भी किसी दूसरी रिक्वेस्ट की तरह 429 के साथ मना कर दिया जाता है। 429 के साथ मना की गई रिक्वेस्ट नहीं गिनी जाती।

हेडर

कुंजी वाली रिक्वेस्ट के हर रिस्पॉन्स में उस पर लागू सीमाएँ होती हैं:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy और RateLimit IETF के ड्राफ़्ट RateLimit header fields for HTTP का पालन करते हैं। हर आइटम एक सीमा है:

X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset इन सीमाओं में से सबसे सख़्त सीमा को आसान रूप में बताते हैं, उन क्लाइंट के लिए जो RateLimit आने से पहले लिखे गए थे। X-RateLimit-Reset सेकंड में है।

जब सीमा पूरी हो जाए

API सेकंड में Retry-After हेडर के साथ 429 Too Many Requests से जवाब देता है:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Retry-After तक इंतज़ार करें और रिक्वेस्ट दोहराएँ। POST और PATCH को उसी Idempotency-Key के साथ दोहराएँ। एरर के रीट्राई हेल्पर ये दोनों काम करते हैं।

प्लान की दूसरी सीमाएँ भी Retry-After के साथ 429 से जवाब देती हैं, उदाहरण के लिए हर दिन के सवालों की संख्या (limits.questions) या एक साथ तैयार हो रहे जवाब (limits.concurrent_answers)। इन्हें भी इसी तरह संभालें।

सीमाओं के अंदर रहना

• RateLimit पढ़ें और r कम होने पर रफ़्तार धीमी करें, 429 का इंतज़ार न करें।
• बड़े काम को समय में फैलाएँ, और जहाँ बैच एंडपॉइंट हैं, वहाँ उन्हें इस्तेमाल करें: 100 दस्तावेज़ों का एक बैच एक रिक्वेस्ट है।
• बदलावों के लिए तेज़ लूप में पोलिंग न करें। वेबहुक को सब्सक्राइब करें, या हर कुछ सेकंड में इवेंट फ़ीड पढ़ें।
• समानांतर वर्कर एक साझा लिमिटर के साथ चलाएँ। एक कुंजी वाली कई प्रोसेस एक ही रेट लिमिट साझा करती हैं।
• अगर आपके इंटीग्रेशन को ज़्यादा चाहिए, तो Sursa में आपके संपर्क व्यक्ति से ऊँची क्लास के बारे में पूछें।