रेट लिमिट

हर अनुरोध पर दो सीमाएं लागू होती हैं: लगभग हर एंडपॉइंट को कवर करने वाली खाता-स्तरीय सीमा, और कुछ एंडपॉइंट पर उनकी अपनी अधिक सख्त सीमा। इनमें से जो कम है, वही आपको मिलेगी।

खाता-स्तरीय सीमा

गणना खाते के हिसाब से, एक मिनट की स्थिर विंडो में होती है। एक ही खाते की सभी API कुंजियां एक ही बजट साझा करती हैं — और कुंजियां बनाने से आपकी सीमा नहीं बढ़ती।

आप कौन हैं	डिफ़ॉल्ट सीमा
पिछली खरीद या सदस्यता वाला खाता, या 10 TRX या उससे अधिक शेष राशि	1000 अनुरोध/मिनट
कोई भी अन्य साइन-इन खाता	300 अनुरोध/मिनट
बिना प्रमाणीकरण के अनुरोध	प्रति IP पते 60 अनुरोध/मिनट
बिना प्रमाणीकरण के `GET /api/v1/invoices/{invoice_id}` की पोलिंग	प्रति IP पते 180 अनुरोध/मिनट

बिना प्रमाणीकरण वाले बजट हर एंडपॉइंट समूह के लिए अलग-अलग गिने जाते हैं — कीमतें, इनवॉइस स्थिति, पते की खोज, प्रमाणीकरण और बाकी सब कुछ — इसलिए कीमतों की पोलिंग बाकी अनुरोधों का बजट कभी नहीं खाती। ये डिफ़ॉल्ट मान हैं। यदि आपके एकीकरण को अधिक ऊंची सीमा चाहिए, तो हम इसे आपके खाते के लिए बढ़ा देते हैं — हमें Telegram पर लिखें।

विंडो स्थिर है, स्लाइडिंग नहीं: काउंटर हर मिनट की शुरुआत में शून्य हो जाता है। पर इस सीमा-रेखा के इर्द-गिर्द बर्स्ट न बनाएं। दो अलग तंत्र इसे घाटे का सौदा बनाते हैं। API के आगे एक एज-सीमा है — प्रति IP पते लगभग 50 अनुरोध प्रति सेकंड — और उसे पार करने पर JSON त्रुटि नहीं, बल्कि HTML बॉडी वाला 503 मिलता है। दूसरा: जो खाता लगातार तीन मिनट अपनी सीमा से ऊपर रहता है, उसकी सीमा अगले दस मिनट के लिए आधी कर दी जाती है; ऐसे तीन मिनट और — तो तीस मिनट के लिए पूरी तरह ब्लॉक, Retry-After: 1800 के साथ। 1000/मिनट वाले खाते इस सीढ़ी से मुक्त हैं।

अपनी अधिक सख्त सीमा वाले एंडपॉइंट

एंडपॉइंट	सीमा	किसके हिसाब से
`POST /api/v1/invoices`	10 अनुरोध/मिनट	IP पता
`POST /api/v1/account/withdrawal`	`Idempotency-Key` के साथ बनी निकासी के बाद 5 सेकंड, उसके बिना बनी निकासी के बाद 60 सेकंड	खाता
`POST /api/v1/energy/auto-refill`	10 अनुरोध/मिनट	खाता
`POST /api/v1/bandwidth/auto-refill`	10 अनुरोध/मिनट	खाता

ध्यान दें कि POST /api/v1/invoices की गणना IP पते के हिसाब से होती है, खाते के नहीं: यदि आपके कई क्लाइंट एक ही आउटगोइंग IP से अनुरोध भेजते हैं, तो वे प्रति मिनट 10 का एक ही बजट साझा करते हैं। खरीद वाले एंडपॉइंट — POST /api/v1/energy/buy, POST /api/v1/energy/activate, POST /api/v1/bandwidth/buy और POST /api/v1/bandwidth/rentals — एक पुराना बजट रखते हैं: 1000 अनुरोध प्रति मिनट, IP पते के हिसाब से (दोनों bandwidth एंडपॉइंट एक ही बजट साझा करते हैं)। किसी एक खाते के लिए यह कभी निर्णायक सीमा नहीं बनता, पर एक ही आउटगोइंग IP के पीछे बैठे क्लाइंट इसे आपस में साझा करते हैं। वेबहुक प्रबंधन एंडपॉइंट (/api/v1/webhooks/...) खाता-स्तरीय सीमा के दायरे में नहीं आते। बाकी सभी प्रलेखित एंडपॉइंट की अपनी सीमा नहीं है — उन पर केवल खाता-स्तरीय सीमा लागू होती है।

429 प्रतिक्रिया कैसी दिखती है

बॉडी इस पर निर्भर करती है कि आप किस सीमा से टकराए। तीन रूप मौजूद हैं, इसलिए किसी एक को मानकर चलने के बजाय बचाव के साथ पार्स करें। खाता-स्तरीय सीमा। प्रतिक्रिया में Retry-After हेडर होता है, जिसमें प्रतीक्षा के सेकंड दिए होते हैं:

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}

एंडपॉइंट की अपनी सीमा, उदाहरण के लिए POST /api/v1/invoices पर। Retry-After हेडर नहीं होता; विंडो एक मिनट की है:

{"detail":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}}

POST /api/v1/account/withdrawal। शेष सेकंड के साथ सादा-पाठ detail, बिना किसी त्रुटि कोड के:

{"detail":"Rate limit: try again in 42s"}

ऐसा 429 जिसे दोबारा कोशिश ठीक नहीं करेगी

POST /api/v1/invoices तब भी 429 देता है जब आपके पास पहले से बहुत अधिक अवैतनिक इनवॉइस हों — अधिकतम 3 प्रति IP पता और अधिकतम 5 प्रति खाता। प्रति-IP सीमा साइन-इन अनुरोधों पर भी लागू होती है, इसलिए आम तौर पर आप पहले उसी से टकराते हैं:

{"detail":"Too many pending invoices (max 3)"}

यह खुले इनवॉइस की संख्या पर सीमा है, रेट लिमिट नहीं, और केवल प्रतीक्षा करने से यह अपने आप नहीं हटती। अगला इनवॉइस बनाने से पहले किसी लंबित इनवॉइस का भुगतान करें, या उसे समाप्त होने दें। यही एंडपॉइंट असंबंधित अस्थायी विफलताओं को भी 429 के रूप में बताता है — उदाहरण के लिए {"detail":"Energy price unavailable"}। प्रतिक्रिया तय करने से पहले संदेश पढ़ें।

दोबारा कोशिश करना

यदि प्रतिक्रिया में Retry-After हेडर है, तो ठीक उतने ही सेकंड प्रतीक्षा करें।
अन्यथा एक सेकंड से शुरू करते हुए घातीय बैकऑफ़ का उपयोग करें।
कभी भी तुरंत दोबारा कोशिश न करें।
दोबारा कोशिश से पहले बॉडी पढ़ें: Too many pending invoices के लिए लंबी प्रतीक्षा नहीं, बल्कि दूसरी कार्रवाई चाहिए।

import time
import requests

def post_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.post(url, **kwargs)
        if resp.status_code == 429:
            body = resp.text
            if "pending invoices" in body:
                raise RuntimeError(body)  # waiting will not help
            delay = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(delay)
            continue
        return resp
    raise RuntimeError("Max retries exceeded")

अधिक ऊंची सीमाएं चाहिए?

उच्च-मात्रा एकीकरणों के लिए कस्टम रेट लिमिट हेतु हमसे Telegram पर संपर्क करें।