दर सीमाएँ

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

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

हर नीति के लिए आपका संगठन एक क्षेत्रीय सीमा साझा करता है, जो उसकी सभी 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 प्रतिक्रिया शामिल नहीं होती। अस्वीकृत कॉल देखें।

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

यदि आपके संगठन के लिए कोई सक्रिय ओवरराइड है, तो वही आपकी प्रभावी दर तय करता है। ओवरराइड न होने पर आपके सक्रिय प्लान का मान लागू होता है; यदि प्लान में उस पॉलिसी का कोई मान नहीं है, तो डिफ़ॉल्ट मान लागू होता है। प्लान या ओवरराइड दर को बढ़ा या घटा सकता है। पॉलिसी की समय अवधि स्थिर रहती है।

अपना प्रभावी कोटा 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');
}

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

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

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

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

अगले चरण

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