दर सीमाएँ

दर सीमाएँ तय करती हैं कि आपका संगठन किसी समय-अवधि में कितने अनुरोध कर सकता है। ट्रैफ़िक की गति नियंत्रित करने के लिए प्रतिक्रिया हेडर का उपयोग करें। अस्वीकार किए गए अनुरोध के बाद फिर से प्रयास करने के लिए बताई गई देरी का पालन करें।

सीमाएँ किस आधार पर लागू होती हैं

हर नीति के लिए आपका संगठन एक क्षेत्रीय सीमा साझा करता है, जो उसकी सभी API कुंजियों और वर्कस्पेस पर लागू होती है। नई कुंजी बनाने से क्षमता नहीं बढ़ती। अलग-अलग संगठनों की सीमाएँ अलग होती हैं।

हर अनुरोध एक ग्राहक नीति का उपयोग करता है। उत्पाद नीतियों की क्षमता अलग होती है: संदेश की स्थिति प्राप्त करने से सामान्य संसाधन-प्राप्ति सीमा का उपयोग नहीं होता, और ईमेल भेजने से संसाधन-निर्माण सीमा का उपयोग नहीं होता।

लॉगिन, पासवर्ड रीसेट और अन्य सुरक्षा-संवेदनशील कार्यों पर दुरुपयोग से बचाव के अतिरिक्त उपाय लागू होते हैं। आपूर्तिकर्ता जाँच और कनेक्शन सीमाएँ भी आपके प्लान की दर सीमाओं से अलग अनुरोधों को अस्वीकार कर सकती हैं।

समूह

सामान्य API कार्य इन नीतियों का उपयोग करते हैं:

उत्पाद कार्य सामान्य API नीति की जगह एक नामित नीति का उपयोग करते हैं। उदाहरण के लिए email_send, email_batch, sms_send, whatsapp_send, lookup और message_status_read। बैच नीतियाँ सबमिशन अनुरोधों की गिनती करती हैं; बैच में प्राप्तकर्ताओं की संख्या से अतिरिक्त नीति इकाइयाँ खर्च नहीं होतीं। बैच के आकार की सीमाओं के लिए ईमेल बैच भेजना और SMS बैच भेजना देखें।

REST ईमेल और SMTP सबमिशन एक ही email_send क्षमता साझा करते हैं। एक SMTP DATA सबमिशन एक इकाई खर्च करता है; SMTP प्रमाणीकरण कोई इकाई खर्च नहीं करता। अगर नीति किसी सबमिशन को अस्वीकार करती है, तो सर्वर फिर से प्रयास की देरी के साथ अस्थायी 452 4.3.1 लौटाता है और संदेश स्वीकार नहीं करता। संदेश को कतार में रखें और उस देरी के बाद फिर से प्रयास करें।

ब्रॉडकास्ट बनाने में api_create का उपयोग होता है, जबकि किसी मौजूदा ब्रॉडकास्ट को शुरू करने में api_update का उपयोग होता है। इसके प्राप्तकर्ताओं को बैकग्राउंड में होने वाली डिलीवरी email_send की खपत नहीं करती। भेजने की अनुमत सीमाएँ और डिलीवरी की गति अलग-अलग नियंत्रण बने रहते हैं।

voice_call नीति इनबाउंड और आउटबाउंड कॉल को स्वीकार किए जाने की सीमा तय करती है। नीति की क्षमता खत्म होने पर कॉल अस्वीकार कर दी जाती है और calls_per_second_exceeded दर्ज किया जाता है; इसमें कोई HTTP प्रतिक्रिया शामिल नहीं होती। अस्वीकृत कॉल देखें।

आपकी सीमा कैसे तय होती है

हर उत्पाद का अपना प्लान होता है, और हर प्लान उस उत्पाद की नीतियों के मान तय करता है: SMS प्लान sms_send और sms_batch तय करता है, Voice प्लान voice_call तय करता है, और इसी तरह आगे भी। ऊँचे स्तर के प्लान ऊँचे मान तय करते हैं। साझा नीतियाँ, जैसे api_* समूह, verify_send, verify_check और message_status_read, किसी भी उत्पाद का प्लान तय कर सकता है।

किसी नीति के लिए आपकी प्रभावी दर इस क्रम में तय होती है:

1. संगठन का सक्रिय ओवरराइड, यदि कोई मौजूद है।
2. आपके संगठन के उन सक्रिय उत्पाद प्लान में सबसे ऊँचा मान, जो उस नीति को तय करते हैं।
3. नीति का डिफ़ॉल्ट मान, जो पे-एज़-यू-गो का आधार स्तर है।

ओवरराइड दर को बढ़ा या घटा सकता है। कोई भी मान लागू हो, नीति की समय-अवधि वही रहती है।

अपना प्रभावी कोटा RateLimit-Policy प्रतिक्रिया हेडर से पढ़ें। यह हेडर नीति कुंजी के साथ उस कॉल पर लागू दर और समय-अवधि बताता है। स्तरों की तुलना करने के लिए हर प्लान का rate_limits सार्वजनिक प्लान कैटलॉग (bird billing plans list --commercial-product sms) से या मूल्य निर्धारण पेज पर दी गई तुलना तालिका से पढ़ें।

सीमा बढ़ाना

अगर नीति पर संगठन का कोई ओवरराइड लागू नहीं है, तो उस नीति वाले उत्पाद का प्लान Billing and payments > Overview में उस उत्पाद के प्लान पेज पर अपग्रेड करें। पहले लक्षित प्लान का rate_limits जाँचें: नई दर तभी लागू होती है जब वह आपके दूसरे प्लान से पहले से मिल रहे मान से ऊँची हो। साझा नीति, जैसे api_get या verify_send, को कोई भी ऐसा उत्पाद प्लान बढ़ा सकता है जो उस नीति को तय करता है। अपग्रेड का भुगतान सफल होते ही ऊँची दर लागू हो जाती है; समय की जानकारी प्लान में बदलाव और नवीनीकरण में दी गई है। प्लान उन कोटा को भी बढ़ाते हैं जो दर सीमाएँ नहीं हैं, जैसे Voice की एक साथ चलने वाली कॉल।

संगठन का सक्रिय ओवरराइड आपके चुने गए किसी भी प्लान के बावजूद लागू रहता है, और यह प्लान के मान से कम भी हो सकता है। अगर RateLimit-Policy हेडर आपके प्लान के प्रकाशित मान से कम दर दिखाता है, तो ओवरराइड की समीक्षा के लिए नीति कुंजी के साथ सहायता टीम से संपर्क करें।

अगर आपको सबसे ऊँचे प्रकाशित प्लान से अधिक क्षमता चाहिए, तो नीति कुंजी और अपने अपेक्षित ट्रैफ़िक के साथ सेल्स से संपर्क करें।

प्रतिक्रिया हेडर

अनुरोध दर सीमा की जाँच IETF Structured Fields फ़ॉर्मैट (RFC 9651) में दो हेडर देती है:

RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35

उद्धृत स्ट्रिंग नीति का नाम बताती है। इस उदाहरण में संगठन की प्रभावी email_send सीमा हर 60 सेकंड में 1,000 सबमिशन है, जिनमें से 842 बचे हैं और रीसेट होने में 35 सेकंड बाकी हैं।

429 मिलने से पहले ही अनुरोधों की गति धीमी करने के लिए r और t का उपयोग करें। t मान सेकंड में एक सापेक्ष देरी है, Unix टाइमस्टैम्प नहीं।

जब आप सीमा तक पहुँच जाएँ

आपके इंटीग्रेशन को 429 प्रतिक्रियाओं को सामान्य संचालन के हिस्से के रूप में संभालना होगा। कम से कम Retry-After का पालन करें और बैकऑफ़ के साथ फिर से प्रयास करें। जो क्लाइंट लाइव RateLimit हेडर के आधार पर अपनी गति भी नियंत्रित करता है (देखें प्रतिक्रिया हेडर), वह सीमा तक नहीं पहुँचता।

ग्राहक नीति समाप्त होने पर 429 Too Many Requests लौटता है, जिसमें सेकंड में Retry-After होता है और अनुरोध दर सीमा हेडर r=0 दिखाते हैं। कोई स्वतंत्र दुरुपयोग या सप्लायर सुरक्षा तब भी 429 लौटा सकती है, जब आपकी ग्राहक नीति में क्षमता बची हो। फिर से प्रयास कब करना है, यह तय करने के लिए Retry-After का पालन करें; यह नीति के t मान से अलग हो सकता है।

बॉडी मानक त्रुटि प्रतिक्रिया का उपयोग करती है:

{
  "error": {
    "type": "rate_limit_error",
    "code": "E01003",
    "name": "RateLimited",
    "message": "Too many requests. Please retry after the period indicated in the Retry-After header.",
    "doc_url": "https://bird.com/docs/api/errors/E01003",
    "request_id": "req_01ky7qavkff7qr88vadv6bv948"
  }
}

type: rate_limit_error के आधार पर ब्रांच करें। मानव-पठनीय संदेश बदल सकता है। नीति कुंजी और फिर से प्रयास का समय हेडर से पढ़ें:

async function sendWithBackoff(url, headers, payload, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload),
    });
    if (response.status !== 429) return response;
    const retryAfter = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error("rate limited after max retries");
}

import time
import requests

def send_with_backoff(url, headers, payload, max_attempts=5):
    for attempt in range(max_attempts):
        response = requests.post(url, headers=headers, json=payload)
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)
    raise RuntimeError("rate limited after max retries")

func sendWithBackoff(req *http.Request, maxAttempts int) (*http.Response, error) {
	for attempt := range maxAttempts {
		if attempt > 0 && req.Body != nil {
			if req.GetBody == nil {
				return nil, errors.New("request body cannot be replayed")
			}
			body, err := req.GetBody()
			if err != nil {
				return nil, err
			}
			req.Body = body
		}
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			return nil, err
		}
		if resp.StatusCode != http.StatusTooManyRequests {
			return resp, nil
		}
		resp.Body.Close()
		wait := 1 << attempt
		if s, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
			wait = s
		}
		time.Sleep(time.Duration(wait) * time.Second)
	}
	return nil, errors.New("rate limited after max retries")
}

function sendWithBackoff(ClientInterface $http, RequestInterface $request, int $maxAttempts = 5): ResponseInterface
{
    for ($attempt = 0; $attempt < $maxAttempts; $attempt++) {
        $response = $http->sendRequest($request);
        if ($response->getStatusCode() !== 429) {
            return $response;
        }
        $retryAfter = (int) ($response->getHeaderLine('Retry-After') ?: 2 ** $attempt);
        sleep($retryAfter);
    }

    throw new RuntimeException('rate limited after max retries');
}

एक ही ऑपरेशन के लिए फिर से प्रयास करते समय उसकी आइडेम्पोटेंसी कुंजी दोबारा उपयोग करें। अनुरोध बॉडी में कोई बदलाव न करें।

स्वचालित फिर से प्रयास और बैकऑफ़ व्यवहार के लिए SDK अवधारणाएँ देखें।

विफलता की स्थिति

रेट लिमिटर फ़ेल-ओपन तरीके से काम करता है: अगर Bird किसी सीमा का मूल्यांकन नहीं कर पाता, तो अनुरोध गलत तरीके से अस्वीकार होने के बजाय आगे बढ़ जाता है। अनुरोध दर सीमित करना सेवा की क्षमता की रक्षा करता है। सुरक्षा की सीमाएँ प्रमाणीकरण और प्राधिकरण ही रहती हैं। Bird की ओर लिमिटर बंद होने से 429 नहीं होता।

अगले चरण

• त्रुटियाँ: त्रुटि प्रतिक्रिया और त्रुटि प्रकारों के आधार पर ब्रांच करने का तरीका
• आइडेम्पोटेंसी: बदलाव करने वाले अनुरोधों के लिए सुरक्षित फिर से प्रयास
• SDK की अवधारणाएँ: स्वचालित फिर से प्रयास और बैकऑफ़ का व्यवहार