rate_limited

HTTP 429 · code: "rate_limited" · type: https://docs.formfeed.dev/errors/rate-limited

Der Workspace hat mehr Anfragen gesendet, die Arbeit auslösen, als sein Plan pro Sekunde erlaubt. Es wurde nichts ausgeführt. limit ist die Größe des Kontingents, das ausgeschöpft ist, window_seconds die Zeit, in der es sich wieder füllt (1 für die Anfragen pro Sekunde des Plans, 60 für die Minute eines Testschlüssels im Free-Plan), und die Antwort trägt Retry-After (wie viele Sekunden Sie warten sollten) sowie die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.

Das Limit ist ein Token-Bucket pro Workspace, den alle seine Schlüssel teilen, Live- wie Test-Schlüssel: Seine Größe und sein Nachfüllen pro Sekunde sind die Anfragen pro Sekunde des Plans, ein kurzer Schub bis zu dieser Größe geht also durch.

Plan	Anfragen pro Sekunde
Free	1
Starter	5
Pro	15
Business	40

Test-Schlüssel im Free-Plan haben ein zweites Kontingent von 30 Anfragen pro Minute.

Beispiel

{
  "type": "https://docs.formfeed.dev/errors/rate-limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "Too many requests for the starter plan; retry in 1s",
  "code": "rate_limited",
  "limit": 5,
  "window_seconds": 1,
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Retry-After: 1
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 1

Häufige Ursachen

• Eine Schleife, die Dokumente einzeln so schnell wie möglich rendert.
• Mehrere Dienste teilen sich einen Workspace.
• Free-Test-Schlüssel senden mehr als 30 Anfragen in einer Minute (dann ist limit 30).

Nur Anfragen, die Arbeit auslösen, zählen: POST an /v1/renders und /v1/renders/batch, die PDF-Tools unter /v1/pdf/, die mit apitemplate.io kompatiblen Endpunkte sowie das Speichern oder Testen einer Speicherverbindung. Lesende Anfragen wie GET /v1/renders/{id} sind nicht begrenzt, Polling löst das Limit also nie aus.

So beheben Sie es

• Warten Sie Retry-After Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die SDKs erledigen das für Sie.
• Senden Sie viele Dokumente als einen Batch statt vieler einzelner Anfragen: bis zu 1.000 Dokumente in einer Anfrage.
• Die Limits pro Plan stehen unter Limits und Verbrauch.

Wiederholen?

Ja, nach den Sekunden aus Retry-After, mit demselben Idempotency-Key. Diese Antwort kommt, bevor der Schlüssel betrachtet wird, und wird nicht gespeichert; die Wiederholung läuft also wirklich.