API-Ratenbegrenzungen

Elido begrenzt die API-Raten pro Schlüssel, nicht pro Workspace. Das bedeutet, dass jede von Ihnen erstellte Integration ihre eigene Begrenzung ausreizen kann, ohne andere zu beeinträchtigen. Dieser Artikel beschreibt die Begrenzungen pro Plan, die zu lesenden Header und wie Sie einen sauberen Backoff implementieren.

Die Zahlen#

Dauerhafte Begrenzungen pro Schlüssel:

Plan	Pro Minute	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Burst ist das, was Sie in einem 10-Sekunden-Fenster kurzzeitig überschreiten können. Dauerhaft ist die Obergrenze im stationären Zustand, mit der sich der Bucket wieder füllt.

Es gibt keine Begrenzungen pro Endpunkt — ein GET /v1/links zählt genauso viel wie ein POST /v1/links. Die einzigen Ausnahmen sind:

• POST /v1/bulk-import — 5 aktive Importe pro Workspace gleichzeitig.
• POST /v1/links mit einem benutzerdefinierten Slug, der mit einem vorhandenen Slug kollidiert — diese zählen trotzdem, führen aber bei einem Konflikt nicht zur Rückerstattung des Slots.
• GET /v1/analytics/timeseries mit interval=second — begrenzt auf 60/Minute, selbst im Business-Plan, da die zugrunde liegende ClickHouse-Abfrage rechenintensiver ist.

Antwort-Header#

Jede API-Antwort enthält:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset ist ein Unix-Zeitstempel, der Ihnen mitteilt, wann der Bucket wieder vollständig gefüllt ist. Verwenden Sie diesen, um erneute Versuche zu planen, anstatt feste Verzögerungen zu nutzen.

Wie ein 429 aussieht#

Wenn Sie die Begrenzung überschreiten:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After wird in Sekunden angegeben. Warten Sie so lange und versuchen Sie es dann erneut. Die SDKs erledigen dies automatisch mit Jitter; wenn Sie einen eigenen HTTP-Client schreiben, tun Sie dasselbe.

Backoff-Strategie#

Wenn Sie die API stark beanspruchen (ein einmaliger Bulk-Job, ein backfill), passen Sie die Geschwindigkeit Ihres Clients an die dauerhafte Begrenzung an und nicht an den Burst. Eine naive Schleife erreicht die Burst-Obergrenze, pausiert dann für 50 Sekunden und erreicht den Burst erneut — was im Durchschnitt schlechter ist als eine gleichmäßige Taktung.

Pseudocode:

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Dieses Muster nutzt 100 % der Begrenzung ohne 429er-Fehler.

Nebenläufigkeit#

Gleichzeitige Anfragen teilen sich den Bucket. Wenn Sie 100 parallele Anfragen aus einem Worker-Pool im Pro-Plan (600/Min) senden, sind die ersten 100 sofort erfolgreich; der Bucket füllt sich dann mit 10/Sek nach. Ihr Worker-Pool sollte eine dauerhafte Rate anstreben, keine Warteschlangentiefe.

Pro Schlüssel vs. pro IP#

Der Bucket gilt pro Schlüssel, nicht pro IP. Wenn Sie denselben Schlüssel von 10 Maschinen aus verwenden, teilen sich die 10 Maschinen die Begrenzung. Erstellen Sie einen Schlüssel pro Maschine, wenn Sie den 10-fachen Spielraum benötigen.

Die IP-Ebene hat eine separate, sehr großzügige Begrenzung (10.000/Min/IP), die nur dazu dient, außer Kontrolle geratene Clients zu stoppen. Im normalen Betrieb werden Sie diese nie erreichen; falls doch, lautet die Antwort 429 mit dem Body "error": "ip_rate_limited".

Idempotenz-Schlüssel bieten keine Umgehung#

Das wiederholte Senden desselben Idempotency-Key zählt weiterhin jede Anfrage gegen Ihren Bucket — wir können die zwischengespeicherte Antwort zurückgeben, ohne die zugrunde liegende Arbeit auszuführen, aber der Zähler wird erhöht. Nutzen Sie Schleifen mit Idempotenz-Schlüsseln nicht als Strategie für erneute Versuche.

Erhöhung der Begrenzungen#

Wenn Ihr Anwendungsfall tatsächlich mehr als 6000/Min dauerhaft benötigt, senden Sie eine E-Mail an support@elido.app mit:

• Ihrer Workspace-ID.
• Dem Namen der Integration.
• Der erwarteten dauerhaften und maximalen Anfragerate.
• Den verwendeten Endpunkten (damit wir die Kapazität für die rechenintensiven planen können).

Wir gewähren Erhöhungen der Begrenzungen pro Schlüssel für Enterprise-Kunden mit Vertrag, in der Regel innerhalb eines Werktages.

Fehlerbehebung#

Plötzliche 429er-Fehler bei einem Schlüssel, der zuvor funktionierte. Entweder hat Ihr Code eine Endlosschleife gestartet (am häufigsten), oder jemand anderes im Workspace hat begonnen, denselben Schlüssel zu verwenden. Überprüfen Sie den Tab Usage des API-Schlüssels im Dashboard für ein Diagramm pro Minute.

429er-Fehler bei der ersten Anfrage des Tages. Buckets im Free-Tarif werden in einem rollierenden Fenster zurückgesetzt, nicht um Mitternacht UTC. Wenn Sie die Begrenzung gestern um 23:59 Uhr getestet haben und sie um 00:01 Uhr noch nicht vollständig aufgefüllt ist, ist der erste Burst immer noch ratenbegrenzt. Warten Sie 60 Sekunden.

X-RateLimit-Remaining ist negativ. Burst-Überschreitung. Die Zahl gibt an, wie tief Sie im negativen Bereich sind; multiplizieren Sie dies mit 60/limit, um die Sekunden zu erhalten, bis Sie wieder bei null sind.