Ratenlimits
Wie viele Anfragen du senden kannst, was passiert, wenn es mehr werden, und welche anderen Grenzen du kennen solltest.
Limits schützen alle, die sich den Dienst teilen. Die Standardwerte sind für normale Nutzung großzügig; triffst du doch eins, sagt dir die Antwort genau, wie lange du warten sollst.
Auf einen Blick
| Limit | Standard | Wenn du es erreichst |
|---|---|---|
Schreibzugriffe pro Konto (createTask, retry, Uploads …) | 1.000 pro 10 Sekunden | 429 mit Retry-After |
Lesezugriffe pro Konto (recordInfo, models, jobs, quote …) | 1.000 pro 10 Sekunden | 429 mit Retry-After |
| Upload-Tickets | 1.000 pro 10 Sekunden, zusätzlich zu den Schreibzugriffen | 429 mit Retry-After |
Nutzungsbericht (/api/v1/usage) | 30 pro Minute und Konto | 429 mit Retry-After |
| Asset-Bibliothek | 60 Lese- und 30 Speichervorgänge pro Minute, dazu eine Tagesgrenze für neue Assets | 429 mit Retry-After |
| Jede Anfrage, bevor der Schlüssel geprüft wird | 6.000 pro Minute und Netzwerk | 429 |
| Request-Body | 2 MiB JSON | 413 |
| Guthaben | Was auf deinem Konto ist | 40201 |
| Ausgabelimits pro Schlüssel | Keine, außer du setzt welche | 40202 |
Limits zählen pro Konto, nicht pro Schlüssel – mehr Schlüssel erhöhen sie nicht.
Antwort-Header
| Header | Bedeutung |
|---|---|
X-RateLimit-Limit | Dein Kontingent im aktuellen Zeitfenster |
X-RateLimit-Remaining | Was davon übrig ist – kommt auch bei erfolgreichen Antworten, damit du früh bremsen kannst |
Retry-After | Bei 429: Sekunden bis zum nächsten Versuch |
Die Zahlen oben sind Standardwerte und können sich ändern; verlass dich auf die Header statt sie fest einzubauen.
So sieht ein Limit aus
{ "code": 429, "msg": "Too many requests. Retry in a moment", "request_id": "req_…" }Eine Anfrage über dem Limit wird sofort abgewiesen – nicht in eine Warteschlange gestellt – und kostet nichts.
Wie du damit umgehst
- Warte mindestens
Retry-AfterSekunden und versuch es dann erneut. Gib etwas zufälligen Jitter dazu, damit nicht alle Clients gleichzeitig zurückkommen. - Wenn du
createTaskwiederholst, schick denselbenIdempotency-Key(Idempotenz). - Polle behutsam: alle paar Sekunden bei Bildern, alle 10–15 Sekunden bei Videos. Noch besser sind Webhooks – sie kosten gar keine Anfragen.
Viele Tasks gleichzeitig
Ratenlimits begrenzen, wie schnell du Anfragen sendest, nicht wie viele Tasks gleichzeitig laufen. Du kannst viele Tasks parallel laufen lassen; lange Videojobs dauern einfach länger. Willst du Tausende Tasks starten, verteil sie über die Zeit und lass die Ergebnisse per Webhook zurückkommen.
Brauchst du für einen Launch oder einen großen Batch ein höheres Kontingent? Schreib uns mit deinem erwarteten Volumen.