Ratenlimits

Certivant erzwingt ein Ratenlimit pro Minute für die API, um die Plattform vor außer Kontrolle geratenen Clients und Lastspitzen anderer Mandanten zu schützen. Bleiben Sie unter dem Limit, sehen Sie nie eine Drosselung; überschreiten Sie es, erhalten Sie eine 429-Antwort mit Headern, die genau angeben, wann Sie erneut versuchen dürfen.

Das Limit

Ihre Obergrenze pro Minute wird durch Ihren Tarif festgelegt. Der Betreiber der Plattform kann außerdem eine Ausnahme pro Kunde gewähren, die stets auf die Obergrenze des Tarifs begrenzt wird. Den tatsächlichen Wert meldet der Header X-RateLimit-Limit bei jeder Antwort — lesen Sie ihn aus, statt einen Wert fest einzutragen.

Standard-Obergrenzen nach Tarif

Dies sind Standardwerte — der Betreiber Ihrer Plattform kann die Obergrenze je Tarif anpassen und Ihrer Organisation ein höheres Limit pro Kunde gewähren (bis zur Obergrenze des Tarifs). Ihr wirksames Limit sehen Sie schreibgeschützt im Dashboard unter KYC → Entwickler.

Wenn Sie für Produktionsverkehr eine höhere Obergrenze benötigen, bitten Sie Ihren Ansprechpartner im Kundenkonto (bei selbst gehosteten Installationen Ihren Plattformbetreiber), die Obergrenze Ihres Tarifs bzw. Ihr Limit pro Kunde anzuheben.

Antwort-Header (bei jeder authentifizierten Antwort)

Jede erfolgreiche Antwort enthält den aktuellen Stand des Ratenlimits:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
Content-Type: application/json

{ "data": [...], "pagination": {...} }

Lesen Sie diese Werte in Ihrem Client aus, um proaktiv zurückzuschalten — warten Sie nicht auf eine 429, wenn Sie X-RateLimit-Remaining: 3 sehen.

Die 429-Antwort

Überschreiten Sie das Limit, liefert die nächste Anfrage:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 120 requests per 60s. Retry in 18s."
  }
}

X-RateLimit-Reset gibt Ihnen genau an, wie lange Sie warten müssen. Verwenden Sie diesen Wert, statt zu raten.

Wiederholungsstrategie

Der einfachste korrekte Handler:

async function withRateLimit<T>(fn: () => Promise<Response>): Promise<T> {
  while (true) {
    const res = await fn();
    if (res.status !== 429) {
      if (!res.ok) throw await readError(res);
      return res.json() as Promise<T>;
    }
    const retryAfterSec = Number(res.headers.get("X-RateLimit-Reset") ?? 60);
    await sleep(retryAfterSec * 1000 + 100); // pad by 100ms for clock skew
  }
}

Drei Eigenschaften sollten Sie beibehalten:

1. Beachten Sie X-RateLimit-Reset. Alles Kürzere trifft nur erneut auf das Limit.
2. Addieren Sie etwa 100 ms Puffer, um Zeitabweichungen zwischen Ihrer Maschine und dem Edge von Certivant auszugleichen.
3. Begrenzen Sie Ihre Wiederholungen, wenn die Anfrage nicht kritisch ist. Fünf Minuten lang bei einem nicht dringenden Listenaufruf zu hämmern, verschwendet Ressourcen auf beiden Seiten.

Mit dem Limit planen

Die größte Einsparung ergibt sich durch Webhooks. Die häufigste Ursache für Support-Anfragen wegen „Ich erreiche das Ratenlimit“ sind Integrationen, die nach Statusänderungen abfragen — tun Sie das nicht, richten Sie stattdessen Webhooks ein.

Verhalten bei Lastspitzen

Das Limit wird als festes Fenster durchgesetzt: Die erste Anfrage startet einen 60-Sekunden-Zähler, und jede Anfrage zählt gegen Ihre Obergrenze, bis dieses Fenster zurückgesetzt wird. Verteilen Sie anhaltenden Verkehr gleichmäßig, statt das gesamte Minutenbudget in den ersten Sekunden zu verbrauchen.

Wenn Sie ein bekanntes Lastmuster haben (z. B. einen täglichen Stapeljob, der 500 Datensätze verarbeitet), verteilen Sie die Aufrufe:

for (const record of records) {
  await processOne(record);
  await sleep(500); // 2 req/s — comfortably under typical ceilings
}

Was passiert, wenn Redis nicht erreichbar ist

Ist die Redis-Instanz für das Ratenlimit vorübergehend nicht erreichbar, lässt Certivant Ihren Verkehr offen durch — es blockiert Ihre Anfragen nicht. Sie erhalten normale 2xx-Antworten, ohne die Header X-RateLimit-*. Sobald Redis wieder verfügbar ist, greift die normale Durchsetzung wieder. Ein Redis-Ausfall auf unserer Seite unterbricht Ihre Integration somit nicht.

Die Zustellung von Webhooks ist getrennt

Das Ratenlimit gilt für Ihre ausgehenden Aufrufe an Certivant. Eingehende Webhook-Zustellungen von Certivant an Ihren Endpunkt verbrauchen kein Kontingent. Ein „Ratenlimit für Webhooks“ müssen Sie nicht beachten.

Öffentliche Endpunkte

Endpunkte, die keinen API-Schlüssel benötigen (GET /api/status, GET /api/kyc/public/status, die Endpunkte zum Einreichen von Formularen), haben ein eigenes Ratenlimit pro IP-Adresse von 60 Anfragen pro Minute. Es gilt für die IP-Adresse des Aufrufers, nicht für einen API-Schlüssel. Es ist bewusst niedrig angesetzt, weil diese Endpunkte ohne Authentifizierung erreichbar sind. Wenn Ihre Oberfläche für Antragsteller dieses Limit erreicht, leiten Sie die Aufrufe stattdessen über Ihr eigenes Backend, damit sie sich eine IP-Adresse unter Ihrer Kontrolle teilen.