> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit API की रेट लिमिट, X-RateLimit हेडर, Retry-After बैकऑफ़, प्रति-endpoint दायरे और 429 हैंडलिंग। प्रोडक्शन ट्रैफ़िक की योजना आत्मविश्वास से बनाएँ।

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

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

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

1. `x-api-key` हेडर → कुंजी-स्कोप्ड काउंटर।
2. `X-Forwarded-For` का पहला हॉप → IP-स्कोप्ड काउंटर।
3. `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` |

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

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

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

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

```http theme={null}
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`) बनाएँ। देखें [प्रोग्रामेटिक पंजीकरण](https://docs.didit.me/hi/integration/programmatic-registration.md#एप्लिकेशन-प्रबंधन)।
* **निर्णय पढ़ने के अनुरोधों को कैश करें।** `/decision/` endpoint तंग पोलिंग लूप के लिए डिज़ाइन नहीं किए गए हैं। रीयल-टाइम अपडेट चाहिए तो [webhook](https://docs.didit.me/hi/integration/webhooks.md) का उपयोग करें, और `GET /v3/session/<id>/decision/` को केवल बैकफ़िल या ऑडिट के लिए कॉल करें।
* **PDF ऑफ़लाइन बनाएँ।** PDF रेंडरिंग CPU-बाउंड है (50/मिनट की सीमा)। इसे हर पेज व्यू पर नहीं, बल्कि सत्र की अंतिम स्थिति तक पहुँचने के बाद कतार से ट्रिगर करें।

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

```javascript theme={null}
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");
}
```

```python theme={null}
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](mailto:support@didit.me) पर ईमेल करें। ओवरराइड हर एप्लिकेशन के लिए अलग से कॉन्फ़िगर किए जाते हैं।


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.