Rate Limits

UnifAPI erzwingt ein Request-Limit: 60 Requests pro 60 Sekunden, pro API-Key. Es gilt für den Key, nicht für den Workspace oder den Endpunkt — zwei Keys desselben Workspace teilen sich kein Budget, und keine Operation hat ein eigenes, strengeres Limit.

Header

Jede Antwort — 2xx, 4xx oder 5xx — trägt das für sie geltende Kontingent, sodass du nie einen Probe-Request brauchst, um deinen Stand zu kennen.

Eine Antwort, in der nie ein API-Key aufgelöst wurde — etwa ein 401 — meldet die Standard-Policy mit vollem Budget. Sie beschreibt das Kontingent, das dich nach der Authentifizierung erwartet, nicht bereits verbrauchte Nutzung.

Browser-Clients können all diese Header lesen: Sie stehen bei Cross-Origin-Antworten in Access-Control-Expose-Headers.

HTTP/1.1 200 OK
RateLimit-Policy: "api-key";q=60;w=60
RateLimit: "api-key";r=57;t=60
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 60

Das Fenster

Das Fenster ist am jüngsten Request des Keys verankert: Der Zähler wird zurückgesetzt, sobald ein volles Fenster ohne Aufrufe dieses Keys vergeht. Es gibt keine Burst-Reserve — entwirf für die Steady-State-Rate, nicht für ein angespartes Guthaben.

429 behandeln

async function call(url: string, init: RequestInit, attempt = 0): Promise<Response> {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;

  const wait = Number(res.headers.get("Retry-After") ?? res.headers.get("RateLimit-Reset") ?? 1);
  await new Promise((r) => setTimeout(r, wait * 1000));
  return call(url, init, attempt + 1);
}

Zwei Regeln für den Alltag:

1. Reguliere das Tempo, bevor du gedrosselt wirst. Lies RateLimit-Remaining bei jeder Antwort und werde langsamer, je näher der Wert an 0 kommt. Erst bei einem 429 zu bremsen, kostet bei allen Workern gleichzeitig einen Round Trip.
2. Beachte Retry-After. Das ist die Wartezeit, die der Limiter tatsächlich braucht; Raten macht es meist schlimmer. Fehlt der Header, nutze RateLimit-Reset. Die Nebenläufigkeit nach einem 429 zu erhöhen hilft nie — das Limit gilt pro Key.

Mehr anfragen

Limits werden pro Key gesetzt, ein höheres Limit ist also eine Konfigurationsänderung und kein Plan-Upgrade. Schreibe an support@unifapi.com mit deiner Workspace-ID, dem Skill oder der Operation, die du ausführst, und einer groben QPS-Schätzung.