> ## 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. # Límit de freqüència de l'API: límits, capçaleres i 429 > Límits de l'API de Didit, capçaleres X-RateLimit, espera amb Retry-After i gestió de l'error 429 per planificar el trànsit de producció. Didit aplica diverses capes de límits de freqüència per mantenir l'API estable i permetre, alhora, ràfegues de trànsit saludables. Els límits s'apliquen **per identificador**: la teva `x-api-key` o, si no n'envies cap, la teva adreça IP de client. Cada àmbit manté un comptador independent amb una finestra lliscant de 60 segons. ## Identificador i excepcions El middleware escull un identificador de límit de freqüència seguint aquest ordre: 1. Capçalera `x-api-key` → comptador per clau. 2. Primer salt de `X-Forwarded-For` → comptador per IP. 3. `REMOTE_ADDR` → comptador per IP. Les crides següents **eludeixen** completament el límit de freqüència: * La `DIDIT_WEBAPP_API_KEY` interna (utilitzada només per la consola de Didit). * Els endpoints protegits pel permís `IsValidSession` (el trànsit de sessions incrustades i de l'SDK). * `GET /system/healthcheck` (servit per `HealthMiddleware` abans d'aquesta pila). * Els webhooks dels proveïdors: Stripe, cribratge AML, callbacks de verificació facial i modificacions de llistes KYC. ## Límits globals Cada sol·licitud autenticada es classifica també pel mètode HTTP en un àmbit genèric, de manera que qualsevol ruta nova hereta un valor per defecte raonable: | Àmbit | Mètodes HTTP | Límit | Finestra | | - | - | - | - | | `generic-get` | `GET` | 600 / min | 60 s | | `generic-write` | `POST`, `PATCH`, `DELETE` | 300 / min | 60 s | | `ingest-write` | `POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/` | 600 / min | 60 s | La creació de transaccions i la ingestió d'esdeveniments es compten a `ingest-write` **en lloc de** `generic-write`: una integració d'ingestió d'alt volum obté 600 sol·licituds per minut per clau d'API sense gastar el pressupost de les seves altres escriptures. Els límits específics dels endpoints (següent secció) s'apliquen **a més** del límit global. El primer àmbit que supera el seu comptador és el que retorna `429`. ## Límits específics dels endpoints El middleware defineix àmbits més restrictius per a les rutes de més impacte: | Àmbit | Endpoint(s) | Límit | Constant del codi font | | - | - | - | - | | `session-v2-create` | `POST /v2/session/`, `POST /v3/session/` | 600 / min | `SESSION_CREATE_RATE_LIMIT` | | `session-decision` | `GET /v1/session//decision/`, `GET /v2/session//decision/` | 100 / min | `SESSION_DECISION_RATE_LIMIT` | | `session-generate-pdf` | `GET /v1/session//generate-pdf/`, `GET /v3/session//generate-pdf/` | 50 / min | `SESSION_PDF_RATE_LIMIT` | | `session-add-images` | `POST`/`PATCH /session//add-images/` | 10 / min | `SESSION_ADD_IMAGES_RATE_LIMIT` | | `session-update-kyc` | `POST`/`PATCH /session//update-data/` | 10 / min | `SESSION_UPDATE_KYC_RATE_LIMIT` | | `session-update-poa` | `POST`/`PATCH /session//update-poa-data/` | 10 / min | `SESSION_UPDATE_POA_RATE_LIMIT` | > [!NOTE] > > `GET /v3/session//decision/` és servit per `SessionV3RetrieveView` i **no** es troba a l'àmbit `session-decision`. Només el regeix el sostre de 600/min de `generic-get`. El límit de 100/min per a decisions s'aplica a les rutes de decisió v1 i v2. > [!WARNING] > > El codi també defineix `FREE_SESSION_RATE_LIMIT = 10` i `PAID_SESSION_RATE_LIMIT = 600`. Aquestes constants **no s'apliquen actualment** a `POST /v3/session/`: aquest endpoint utilitza el límit únic `session-v2-create` de 600/min per a totes les aplicacions. No planifiquis la capacitat en funció d'un límit per flux de treball del pla gratuït fins que no estigui documentat com a actiu. ## Forma de la resposta 429 Quan superes qualsevol àmbit reps un HTTP `429` amb aquest cos i aquestes capçaleres: ```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." } ``` | Capçalera | Significat | | - | - | | `X-RateLimit-Limit` | Nombre màxim de sol·licituds permeses a la finestra actual per a l'àmbit que ha activat el límit. | | `X-RateLimit-Remaining` | Sol·licituds restants abans que es reiniciï la finestra. Queda limitat a `0` quan superes el límit. | | `X-RateLimit-Reset` | Segons des de l'època Unix en què el comptador es reinicia a zero. | | `Retry-After` | Segons que cal esperar abans del següent intent, arrodonits cap amunt perquè esperar-los sempre et porti a la finestra següent. Hi és **només a les respostes `429`**, no a totes les sol·licituds. | Les capçaleres `X-RateLimit-*` només s'emeten a la resposta `429`: les respostes satisfactòries no les inclouen actualment. Utilitza el valor de `Retry-After` (o `X-RateLimit-Reset - now`) com a retard abans del següent intent. ## Orientació per al client * **Respecta `Retry-After`** com a límit inferior del teu backoff. Per sobre, aplica un backoff exponencial amb variació aleatòria (jitter) (`5s → 10s → 20s → 40s ± random`), perquè dos clients que rebin un `429` al mateix temps no se sincronitzin. * **Atura els reintents** després d'un límit petit (per exemple, 5 intents). Propaga l'error al codi que t'ha cridat i avisa el teu equip: els 429 sostinguts normalment indiquen un bucle descontrolat, no un pic puntual. * **Fes servir un identificador per càrrega de treball.** Compartir un `x-api-key` entre molts backends fa que quedin agrupats en el mateix comptador, i un veí sorollós pot deixar la resta sense recursos. Crea una aplicació separada (i, per tant, un `api_key` separat) per entorn, marca o client; consulta [Registre programàtic](https://docs.didit.me/ca/integration/programmatic-registration.md#gestió-d’aplicacions). * **Desa en memòria cau les lectures de decisió.** Els endpoints `/decision/` no estan pensats per a bucles de sondeig intensius. Si necessites actualitzacions en temps real, fes servir [Webhooks](https://docs.didit.me/ca/integration/webhooks.md) i crida `GET /v3/session//decision/` només per completar les dades que faltin o per auditoria. * **Genera els PDF fora de línia.** La renderització de PDF requereix molta CPU (límit de 50 per minut). Activa-la des d'una cua quan la sessió arribi a un estat final, no en cada visualització de pàgina. ## Exemple de client que gestiona el 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") ``` ## Necessites més capacitat? Si 600 sessions per minut no són suficients, per exemple per a un llançament de màrqueting o un completament de dades històriques, escriu a [support@didit.me](mailto:support@didit.me) indicant l'UUID de la teva `application` i els ritmes sostinguts i de ràfega que preveus. Les excepcions es configuren per aplicació. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.