Telm misst die API auf zwei Arten: ein Ratenlimit pro Minute (eine Burst-Obergrenze) und ein Tageskontingent (Ihr Gesamtbudget für den UTC-Tag). Beide skalieren mit dem Plan. Jede kontingentierte Antwort liefert X-Quota-Limit, X-Quota-Used und X-Quota-Reset, sodass Sie stets Ihr verbleibendes Budget kennen, und beide Limits liefern bei Überschreitung 429 mit einem Retry-After-Header.
1Zwei Limits: Minutenrate und Tageskontingent
Es gibt zwei separate Obergrenzen. Das Ratenlimit pro Minute begrenzt, wie viele Anfragen Sie innerhalb einer einzelnen Minute stellen können, und glättet Bursts. Das Tageskontingent ist Ihr Gesamtbudget: Es begrenzt, wie viele kontingentierte Aufrufe Sie über den ganzen UTC-Tag hinweg machen können.
Sie sind unabhängig. Sie können das Minutenlimit erreichen, während Sie noch reichlich Tageskontingent übrig haben (Sie senden schlicht zu schnell), oder Ihr Tageskontingent aufbrauchen, während Sie deutlich unter dem Minutenlimit liegen (Sie haben den Tag verbraucht). Beide geben einen 429-Status zurück, aber aus unterschiedlichen Gründen — prüfen Sie den Fehlercode im Body, um sie zu unterscheiden.
- Minuten-Ratenlimit — eine Burst-Obergrenze, wird jede Minute zurückgesetzt.
- Tageskontingent — Ihre gesamten gemessenen Aufrufe für den Tag, wird um Mitternacht UTC zurückgesetzt.
- Das Kontingent wird einmal pro Konto gezählt und über alle Ihre Schlüssel geteilt.
2Tageskontingent nach Plan
Ihr Tageskontingent ist die Anzahl der kontingentierten API-Aufrufe, die Sie pro UTC-Tag machen können, und es hängt von Ihrem Plan ab. Der Zähler wird über all Ihre Schlüssel geteilt und folgt dem besten Plan unter den Gruppen, die Sie verwalten — ohne kostenpflichtiges Abonnement sind Sie auf der Free-Stufe.
Das Fenster ist der UTC-Kalendertag, sodass Ihr Verbrauchszähler um Mitternacht UTC auf null zurückgesetzt wird. Eine Stapel-Spam-Prüfung kostet einen Aufruf pro Element im Stapel, nicht einen Aufruf für die gesamte Anfrage.
- Free — 100 Aufrufe pro Tag.
- Basic — 1.000 Aufrufe pro Tag.
- Pro — 10.000 Aufrufe pro Tag.
- Business — 50.000 Aufrufe pro Tag.
3Minuten-Ratenlimit nach Plan
Zusätzlich zum Tageskontingent ist jeder API-Schlüssel auf eine Anzahl von Anfragen pro Minute entsprechend seiner Planstufe begrenzt. Dies ist ein Glättungslimit: Es hindert einen einzelnen Client daran, in einer Sekunde eine riesige Spitze zu senden, selbst wenn das Tagesbudget noch lange nicht aufgebraucht ist.
Getrennt davon gelten breite Obergrenzen pro IP und pro Konto über die gesamte API hinweg, um die Plattform stabil zu halten. Im normalen Gebrauch — stetige, getaktete Anfragen — berühren Sie diese nie; sie greifen nur bei missbräuchlichen Bursts.
- Free und Basic — 60 Anfragen pro Minute.
- Pro — 600 Anfragen pro Minute.
- Business — 1.800 Anfragen pro Minute.
- Verteilen Sie Anfragen, anstatt sie alle auf einmal abzufeuern.
4Ihr verbleibendes Budget lesen
Sie müssen nie raten, wie viel Kontingent übrig ist. Jede gemessene Antwort — Erfolg oder Fehlschlag — enthält drei Header: X-Quota-Limit (Ihr Tageslimit), X-Quota-Used (wie viele Aufrufe Sie heute verbraucht haben) und X-Quota-Reset (der Zeitpunkt in UTC, an dem der Zähler zurückgesetzt wird).
Die Spam-Prüf-Endpunkte geben dieselben Zahlen auch im Antwort-Body unter einem quota-Objekt zurück, sodass Sie Ihr verbleibendes Budget lesen können, ohne Header zu parsen. Nutzen Sie diese, um Ihre eigenen Anfragen zu takten und sich zu warnen, bevor Sie das Kontingent aufbrauchen.
- X-Quota-Limit — Ihr tägliches Aufruflimit.
- X-Quota-Used — bisher heute verbrauchte Aufrufe.
- X-Quota-Reset — Rücksetzzeitpunkt in UTC (RFC 3339).
- Die Spam-Prüf-Antworten enthalten außerdem ein quota-Objekt mit denselben Feldern.
5Was bei 429 passiert
Wenn Sie eines der Limits überschreiten, gibt die API HTTP 429 mit einem Retry-After-Header zurück, der Ihnen sagt, wie viele Sekunden Sie warten sollen. Beim Minuten-Ratenlimit beträgt Retry-After etwa eine Minute. Beim Tageskontingent trägt der Body einen daily_quota_exceeded-Code plus Ihren Plan, das Limit, die Verbrauchszahl, den Rücksetzzeitpunkt und einen Upgrade-Hinweis, und Retry-After zählt bis Mitternacht UTC herunter.
Der richtige Umgang mit 429 ist, zurückzustecken und nach der Retry-After-Verzögerung erneut zu versuchen, nicht den Endpunkt zu bombardieren. Gut funktionierende Clients lesen den Header und pausieren; Clients, die sofort weiter wiederholen, bleiben einfach blockiert.
- 429 rate_limit_exceeded — Sie haben zu schnell gesendet; warten Sie etwa eine Minute.
- 429 daily_quota_exceeded — der Tag ist verbraucht; warten Sie bis zur UTC-Rücksetzung oder führen Sie ein Upgrade durch.
- Beachten Sie vor einem erneuten Versuch immer den Retry-After-Header.