Limiti di frequenza API: header, errori 429 e backoff

​

Identificatore ed esenzioni

1. Intestazione x-api-key → contatore per chiave.
2. Primo hop di X-Forwarded-For → contatore per IP.
3. REMOTE_ADDR → contatore per IP.

• La DIDIT_WEBAPP_API_KEY interna (usata solo dalla console di Didit).
• Gli endpoint protetti dal permesso IsValidSession (il traffico delle sessioni integrate e dell’SDK).
• GET /system/healthcheck (servito da HealthMiddleware prima di questo stack).
• I webhook dei provider: Stripe, Screening AML, callback di verifica facciale e modifiche alle liste KYC.

​

Limiti globali

​

Limiti specifici per endpoint

​

Struttura della risposta 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."
}

​

Linee guida per il client

• Rispetta Retry-After come valore minimo del backoff. A questo, aggiungi un backoff esponenziale con jitter (5s → 10s → 20s → 40s ± random) in modo che due client che ricevono 429 nello stesso momento non si sincronizzino.
• Interrompi i tentativi dopo un limite ridotto (ad esempio 5 tentativi). Restituisci l’errore al chiamante e avvisa il tuo team: 429 ripetuti indicano di solito un loop incontrollato, non un picco temporaneo.
• Usa un unico identificatore per ogni carico di lavoro. Condividere una x-api-key tra molti backend li fa confluire nello stesso contatore, e può far sì che un vicino rumoroso lasci gli altri senza risorse. Crea un’applicazione separata (e quindi un api_key separato) per ambiente, marchio o cliente: vedi Registrazione programmatica.
• Metti in cache le letture delle decisioni. Gli endpoint /decision/ non sono progettati per cicli di polling serrati; se ti servono aggiornamenti in tempo reale, usa i Webhook e chiama GET /v3/session/<id>/decision/ solo per il recupero dei dati arretrati o per l’audit.
• Genera i PDF offline. Il rendering dei PDF è limitato dalla CPU (tetto di 50/min). Avvialo da una coda una volta che la sessione raggiunge uno stato finale, non a ogni visualizzazione di pagina.

​

Esempio di client con gestione dei 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")

​

Hai bisogno di più capacità?