API-Rate-Limiting: Limits, Header & 429-Backoff

​

Kennung und Ausnahmen

1. x-api-key-Header → Zähler auf Schlüssel-Ebene.
2. Erster Hop in X-Forwarded-For → Zähler auf IP-Ebene.
3. REMOTE_ADDR → Zähler auf IP-Ebene.

• Der interne DIDIT_WEBAPP_API_KEY (ausschließlich von der Didit-Konsole verwendet).
• Endpoints, die durch die Berechtigung IsValidSession geschützt sind (der Traffic von eingebetteten Sitzungen/SDK-Sitzungen).
• GET /system/healthcheck (wird von HealthMiddleware vor diesem Stack verarbeitet).
• Provider-Webhooks: Stripe, AML-Screening, Callbacks zur Gesichtsverifizierung, Änderungen von KYC-Listen.

​

Globale Limits

​

Endpoint-spezifische Limits

​

Format der 429-Antwort

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."
}

​

Empfehlungen für Clients

• Beachten Sie Retry-After als Mindestwert für Ihr Backoff. Nutzen Sie darauf aufbauend ein exponentielles Backoff mit Jitter (5s → 10s → 20s → 40s ± random), damit sich zwei Clients, die gleichzeitig auf einen 429 stoßen, nicht synchronisieren.
• Brechen Sie Wiederholungsversuche nach einer geringen Obergrenze (z. B. 5 Versuchen) ab. Leiten Sie den Fehler an Ihren Aufrufer weiter und benachrichtigen Sie Ihr Team – anhaltende 429-Fehler weisen in der Regel auf eine Endlosschleife hin, nicht auf eine vorübergehende Spitze.
• Verwenden Sie einen Bezeichner pro Workload. Wenn Sie einen x-api-key über mehrere Backends hinweg teilen, fallen diese in denselben Zähler, was dazu führen kann, dass ein störender Nachbar die übrigen ausbremst. Erstellen Sie eine separate Anwendung (und somit einen separaten api_key) pro Umgebung, Marke oder Kunde – siehe Programmatische Registrierung.
• Cachen Sie Entscheidungsabfragen. Die /decision/-Endpoints sind nicht für enge Polling-Schleifen ausgelegt; wenn Sie Echtzeit-Updates benötigen, nutzen Sie Webhooks und rufen Sie GET /v3/session/<id>/decision/ nur für Backfills oder Audits auf.
• Generieren Sie PDFs offline. Das Rendern von PDFs ist CPU-intensiv (Begrenzung auf 50/Min.). Lösen Sie dies über eine Warteschlange aus, nachdem die Sitzung einen finalen Status erreicht hat, und nicht bei jedem Seitenaufruf.

​

Beispiel für einen 429-kompatiblen Client

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")

​

Benötigen Sie mehr Spielraum?