PDF Blocks
Seite öffnen

Rate-Limits und Nutzung

Wie Anfragen auf Ihren Plan angerechnet werden, wie die Antwort 429 aussieht und welche Größenbeschränkung für eine einzelne Anfrage gilt.

Vorausschauend. Rate-Limiting, Nutzungsobergrenzen und die Antworten 402, 403 und 429 sind Teil des API-Vertrags, werden aber noch nicht durchgesetzt. Diese Seite beschreibt ihr Verhalten, damit Sie einen Client bauen können, der darauf vorbereitet ist. Dafür werden hier keine Zahlenwerte veröffentlicht, weil keine in Kraft sind. Eine Ausnahme sind die Größenbeschränkungen für Anfragen: Sie gelten schon heute, das Limit steht weiter unten.

PDF Blocks ist darauf ausgelegt, unter Last kontrolliert nachzugeben und Ihre Nutzung sichtbar zu halten. Diese Seite behandelt, wie die Nutzung gemessen wird, wie sich Rate-Limiting äußert und wie Sie Ihre Anfragen dimensionieren.

Wie die Nutzung gemessen wird

Die Nutzung wird pro Plan gemessen und in Ihrem Dashboard nachgehalten. Das Dashboard ist die maßgebliche Quelle dafür, was Sie auf Ihren Plan verbraucht haben: sowohl die Anzahl der verarbeiteten Dokumente als auch die Anzahl der gestellten Anfragen. Prüfen Sie es, um Ihren Verbrauch zu überwachen und zu sehen, wie nah Sie am Kontingent Ihres Plans sind.

Weil die API stateless ist, wird jede Anfrage für sich gemessen; es gibt keine Sitzungen und keine Stapel, die abzugleichen wären. Eine Aktion mit mehreren Dokumenten wie ein Aufteilen zählt trotzdem als eine einzige Anfrage.

Rate-Limits und die Antwort 429

Sobald Rate-Limiting durchgesetzt wird, werden Anfragen, die das Kontingent Ihres Plans überschreiten, mit 429 Too Many Requests und einem Antworttext vom Typ problem+json beantwortet. Ein 429 ist vorübergehend: Dieselbe Anfrage gelingt, sobald Sie langsamer werden.

Bauen Sie Ihre Clients von Anfang an so, dass sie damit umgehen:

  • Exponentielles Backoff verwenden. Warten Sie bei einem 429, bevor Sie es erneut versuchen, und erhöhen Sie die Verzögerung mit jedem weiteren 429 (zum Beispiel durch Verdoppeln), statt sofort in einer engen Schleife erneut zu senden.
  • Retry-After beachten. Trägt die Antwort einen Header Retry-After, warten Sie mindestens so lange, bevor Sie es erneut versuchen, statt Ihre eigene Verzögerung zu verwenden.
  • Jitter hinzufügen. Variieren Sie die Wartezeit leicht zufällig, damit parallele Worker nicht im Gleichtakt erneut senden.
  • Versuche begrenzen. Geben Sie nach einer sinnvollen Anzahl von Versuchen auf und melden Sie den Fehler, statt endlos zu wiederholen.

Dieselbe Backoff-Strategie gilt für den seltenen Serverfehler 5xx.

Größenbeschränkungen für Anfragen

Jeder Plan begrenzt die Größe eines einzelnen Eingabedokuments: 5 MB bei Free, 10 MB bei jedem anderen Plan (siehe Preise). Eine Anfrage, deren Text dieses Limit überschreitet, wird mit 413 Payload Too Large abgelehnt und gibt einen Antworttext vom Typ problem+json zurück, ohne verarbeitet zu werden. Anders als ein 429 gelingt ein 413 auch bei einem erneuten Versuch nicht: Senden Sie eine kleinere Datei, oder fragen Sie uns, ob wir das Limit für Ihr Konto anheben können, wenn Sie regelmäßig mehr benötigen.

Antworten rund um die Abrechnung

Zwei weitere reservierte Codes betreffen Ihr Konto und nicht die einzelne Anfrage:

  • 402 Payment Required: eine Bedingung bei der Abrechnung oder beim Kontingent Ihres Plans. Klären Sie sie im Dashboard.
  • 403 Forbidden: Ihr Schlüssel ist gültig, darf die angeforderte Ressource aber nicht verwenden.

Beide stehen im Katalog Fehler, zusammen mit der vollständigen Form der Antwort.