API रेट लिमिट: सीमाएँ, हेडर और 429 बैकऑफ़

Didit कई स्तरों पर रेट लिमिटिंग लागू करता है, ताकि API स्थिर रहे और साथ ही ट्रैफ़िक के सामान्य उछाल की अनुमति भी मिले। लिमिट हर पहचानकर्ता के लिए अलग से लागू होती हैं: आपकी x-api-key, या अगर कोई API कुंजी नहीं भेजी गई हो तो आपका क्लाइंट IP। हर स्कोप का अपना स्वतंत्र काउंटर होता है और उसकी विंडो 60 सेकंड की स्लाइडिंग विंडो होती है।

पहचानकर्ता और छूट

मिडलवेयर रेट-लिमिट पहचानकर्ता इस क्रम में चुनता है:

x-api-key हेडर → कुंजी-स्कोप्ड काउंटर।
X-Forwarded-For का पहला हॉप → IP-स्कोप्ड काउंटर।
REMOTE_ADDR → IP-स्कोप्ड काउंटर।

निम्नलिखित कॉल्स पर रेट लिमिटिंग पूरी तरह बायपास होती है:

आंतरिक DIDIT_WEBAPP_API_KEY (केवल Didit कंसोल द्वारा उपयोग की जाती है)।
IsValidSession अनुमति से सुरक्षित endpoint (एम्बेडेड/SDK सत्र ट्रैफ़िक)।
GET /system/healthcheck (यह इस स्टैक से पहले HealthMiddleware द्वारा दिया जाता है)।
प्रोवाइडर webhook: Stripe, AML स्क्रीनिंग, चेहरा सत्यापन कॉलबैक, KYC सूची में बदलाव।

वैश्विक लिमिट

हर प्रमाणित अनुरोध HTTP मेथड के आधार पर एक सामान्य स्कोप में भी गिना जाता है, ताकि कोई नया रूट एक उचित डिफ़ॉल्ट पा सके:

स्कोप	HTTP मेथड	लिमिट	विंडो
`generic-get`	`GET`	600 / मिनट	60 सेकंड
`generic-write`	`POST`, `PATCH`, `DELETE`	300 / मिनट	60 सेकंड
`ingest-write`	`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`	600 / मिनट	60 सेकंड

लेन-देन बनाना और इवेंट इनजेस्शन generic-write के बजाय ingest-write में गिने जाते हैं: उच्च मात्रा वाला इनजेस्शन इंटीग्रेशन हर API कुंजी के लिए प्रति मिनट 600 अनुरोध पाता है, और उसके अन्य राइट अनुरोधों का बजट खर्च नहीं होता। endpoint-विशिष्ट लिमिट (अगला सेक्शन) वैश्विक लिमिट के अतिरिक्त लागू होती हैं। जो स्कोप सबसे पहले अपना काउंटर पार करता है, वही 429 लौटाता है।

endpoint-विशिष्ट लिमिट

मिडलवेयर सबसे अधिक प्रभाव वाले रूट्स के लिए सख़्त स्कोप परिभाषित करता है:

स्कोप	endpoint	लिमिट	सोर्स कॉन्स्टेंट
`session-v2-create`	`POST /v2/session/`, `POST /v3/session/`	600 / मिनट	`SESSION_CREATE_RATE_LIMIT`
`session-decision`	`GET /v1/session/<id>/decision/`, `GET /v2/session/<id>/decision/`	100 / मिनट	`SESSION_DECISION_RATE_LIMIT`
`session-generate-pdf`	`GET /v1/session/<id>/generate-pdf/`, `GET /v3/session/<id>/generate-pdf/`	50 / मिनट	`SESSION_PDF_RATE_LIMIT`
`session-add-images`	`POST`/`PATCH /session/<id>/add-images/`	10 / मिनट	`SESSION_ADD_IMAGES_RATE_LIMIT`
`session-update-kyc`	`POST`/`PATCH /session/<id>/update-data/`	10 / मिनट	`SESSION_UPDATE_KYC_RATE_LIMIT`
`session-update-poa`	`POST`/`PATCH /session/<id>/update-poa-data/`	10 / मिनट	`SESSION_UPDATE_POA_RATE_LIMIT`

GET /v3/session/<id>/decision/ को SessionV3RetrieveView सर्व करता है और यह session-decision स्कोप में शामिल नहीं है। इस पर केवल generic-get की 600/मिनट की ऊपरी सीमा लागू होती है। 100/मिनट वाली निर्णय थ्रॉटल v1 और v2 निर्णय पाथ पर लागू होती है।

कोडबेस में FREE_SESSION_RATE_LIMIT = 10 और PAID_SESSION_RATE_LIMIT = 600 भी परिभाषित हैं। ये कॉन्स्टेंट्स फ़िलहाल POST /v3/session/ पर लागू नहीं हैं। यह endpoint हर एप्लिकेशन के लिए एकल session-v2-create लिमिट, यानी 600/मिनट, का उपयोग करता है। जब तक प्रति वर्कफ़्लो निःशुल्क स्तर थ्रॉटल को लाइव के रूप में दस्तावेज़ित न किया जाए, उसके आधार पर क्षमता योजना न बनाएँ।

429 रिस्पॉन्स का स्वरूप

जब आप किसी भी स्कोप की सीमा पार करते हैं, तो आपको इस बॉडी और हेडर्स के साथ HTTP 429 मिलता है:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1762534870
Retry-After: 37

{
  "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute."
}

हेडर	अर्थ
`X-RateLimit-Limit`	उस स्कोप के लिए, जिसकी सीमा पार हुई, वर्तमान विंडो में अधिकतम अनुमत अनुरोध।
`X-RateLimit-Remaining`	विंडो रीसेट होने से पहले शेष अनुरोध। लिमिट पार होने पर यह `0` पर सीमित हो जाता है।
`X-RateLimit-Reset`	Unix epoch सेकंड, जब काउंटर शून्य पर रीसेट होता है।
`Retry-After`	अगला प्रयास करने से पहले प्रतीक्षा करने के लिए सेकंडों की संख्या, जिसे ऊपर की ओर पूर्णांकित किया गया है, ताकि इतनी प्रतीक्षा करने पर अनुरोध हमेशा अगली विंडो में पहुँचे। यह केवल `429` रिस्पॉन्स पर मौजूद होता है, हर अनुरोध पर नहीं।

X-RateLimit-* हेडर्स केवल 429 रिस्पॉन्स पर भेजे जाते हैं। वर्तमान में सफल रिस्पॉन्स में ये शामिल नहीं होते। अगले प्रयास से पहले की देरी के रूप में Retry-After का मान (या X-RateLimit-Reset - now) उपयोग करें।

क्लाइंट मार्गदर्शन

Retry-After का सम्मान करें और इसे अपने बैकऑफ़ की न्यूनतम सीमा मानें। इसके ऊपर जिटर वाला एक्सपोनेंशियल बैकऑफ़ जोड़ें (5s → 10s → 20s → 40s ± random), ताकि एक ही समय पर 429 पाने वाले दो क्लाइंट एक-दूसरे के साथ सिंक्रोनाइज़ न हों।
एक सीमित संख्या के बाद पुनः प्रयास बंद करें (जैसे 5 प्रयास)। त्रुटि को अपने कॉलर तक पहुँचाएँ और अपनी टीम को अलर्ट करें। लगातार 429 आम तौर पर बेकाबू लूप का संकेत होता है, क्षणिक उछाल का नहीं।
हर वर्कलोड के लिए एक पहचानकर्ता इस्तेमाल करें। कई बैकएंड के बीच एक x-api-key साझा करने से वे एक ही काउंटर में गिने जाते हैं, जिससे एक भारी उपयोग करने वाला क्लाइंट बाकी सबके हिस्से की क्षमता खा सकता है। हर एनवायरनमेंट, ब्रांड या ग्राहक के लिए अलग एप्लिकेशन (और इसलिए अलग api_key) बनाएँ। देखें प्रोग्रामेटिक पंजीकरण।
निर्णय पढ़ने के अनुरोधों को कैश करें। /decision/ endpoint तंग पोलिंग लूप के लिए डिज़ाइन नहीं किए गए हैं। रीयल-टाइम अपडेट चाहिए तो webhook का उपयोग करें, और GET /v3/session/<id>/decision/ को केवल बैकफ़िल या ऑडिट के लिए कॉल करें।
PDF ऑफ़लाइन बनाएँ। PDF रेंडरिंग CPU-बाउंड है (50/मिनट की सीमा)। इसे हर पेज व्यू पर नहीं, बल्कि सत्र की अंतिम स्थिति तक पहुँचने के बाद कतार से ट्रिगर करें।

429 के प्रति जागरूक नमूना क्लाइंट

async function postSession(body) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch("https://verification.didit.me/v3/session/", {
      method: "POST",
      headers: {
        "x-api-key": process.env.DIDIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Didit: too many 429s, giving up");
}

import os
import random
import time

import httpx

def post_session(body: dict) -> httpx.Response:
    with httpx.Client(timeout=15) as client:
        for _ in range(5):
            resp = client.post(
                "https://verification.didit.me/v3/session/",
                headers={
                    "x-api-key": os.environ["DIDIT_API_KEY"],
                    "Content-Type": "application/json",
                },
                json=body,
            )
            if resp.status_code != 429:
                return resp
            wait_s = float(resp.headers.get("Retry-After", "1")) + random.random()
            time.sleep(wait_s)
    raise RuntimeError("Didit: too many 429s, giving up")

और क्षमता चाहिए?

अगर 600 सत्र प्रति मिनट पर्याप्त नहीं हैं, जैसे किसी मार्केटिंग लॉन्च या बैकफ़िल के लिए, तो अपने application UUID और अपेक्षित लगातार तथा बर्स्ट दरों के साथ support@didit.me पर ईमेल करें। ओवरराइड हर एप्लिकेशन के लिए अलग से कॉन्फ़िगर किए जाते हैं।

गाइड

प्रमाणीकरण

Model Context Protocol (MCP)

वेब SDK

नेटिव SDK

सर्वर SDK

इंटीग्रेशन

API रेट लिमिट: सीमाएँ, हेडर और 429 बैकऑफ़

पहचानकर्ता और छूट

वैश्विक लिमिट

endpoint-विशिष्ट लिमिट

429 रिस्पॉन्स का स्वरूप

क्लाइंट मार्गदर्शन

429 के प्रति जागरूक नमूना क्लाइंट

और क्षमता चाहिए?

​पहचानकर्ता और छूट

​वैश्विक लिमिट

​endpoint-विशिष्ट लिमिट

​429 रिस्पॉन्स का स्वरूप

​क्लाइंट मार्गदर्शन

​429 के प्रति जागरूक नमूना क्लाइंट

​और क्षमता चाहिए?

पहचानकर्ता और छूट

वैश्विक लिमिट

endpoint-विशिष्ट लिमिट

429 रिस्पॉन्स का स्वरूप

क्लाइंट मार्गदर्शन

429 के प्रति जागरूक नमूना क्लाइंट

और क्षमता चाहिए?