Telm mierzy API na dwa sposoby: limit na minutę (pułap serii) oraz dzienny przydział (Twój całkowity budżet na dzień UTC). Oba skalują się z planem. Każda mierzona odpowiedź zwraca X-Quota-Limit, X-Quota-Used i X-Quota-Reset, więc zawsze znasz pozostały budżet, a oba limity zwracają 429 z nagłówkiem Retry-After po przekroczeniu.
1Dwa limity: na minutę i dzienny przydział
Istnieją dwa oddzielne pułapy. Limit na minutę ogranicza, ile żądań możesz wykonać w obrębie pojedynczej minuty, wygładzając serie. Dzienny przydział to Twój ogólny budżet: ogranicza, ile mierzonych wywołań możesz wykonać przez cały dzień UTC.
Są niezależne. Możesz osiągnąć limit na minutę, wciąż mając mnóstwo dziennego przydziału (po prostu wysyłasz zbyt szybko), albo wyczerpać dzienny przydział, będąc znacznie poniżej limitu na minutę (wykorzystałeś dzień). Oba zwracają status 429, ale z różnych powodów — sprawdź kod błędu w treści, aby je rozróżnić.
- Limit na minutę — pułap serii, resetuje się co minutę.
- Dzienny przydział — Twoje całkowite mierzone wywołania na dzień, resetuje się o północy UTC.
- Przydział liczony jest raz na konto, współdzielony przez wszystkie Twoje klucze.
2Dzienny przydział według planu
Twój dzienny przydział to liczba mierzonych wywołań API, które możesz wykonać na dzień UTC, i zależy on od Twojego planu. Licznik jest współdzielony przez wszystkie Twoje klucze i podąża za najlepszym planem spośród grup, którymi administrujesz — bez płatnej subskrypcji jesteś na poziomie Free.
Oknem jest kalendarzowy dzień UTC, więc Twój licznik zużycia resetuje się do zera o północy UTC. Wsadowe sprawdzenie spamu kosztuje jedno wywołanie na element wsadu, a nie jedno wywołanie na całe żądanie.
- Free — 100 wywołań dziennie.
- Basic — 1000 wywołań dziennie.
- Pro — 10 000 wywołań dziennie.
- Business — 50 000 wywołań dziennie.
3Limit na minutę według planu
Ponad dzienny przydział, każdy klucz API jest ograniczony do liczby żądań na minutę zgodnie ze swoim poziomem planu. To limit wygładzający: powstrzymuje pojedynczego klienta od wysłania ogromnego skoku w jednej sekundzie, nawet gdy dzienny budżet jest daleki od wyczerpania.
Oddzielnie, szerokie pułapy per IP i per konto obowiązują w całym API, by utrzymać stabilność platformy. Przy normalnym użyciu — stałych, rozłożonych żądaniach — nigdy ich nie dotkniesz; uruchamiają się tylko przy nadużywających seriach.
- Free i Basic — 60 żądań na minutę.
- Pro — 600 żądań na minutę.
- Business — 1800 żądań na minutę.
- Rozkładaj żądania w czasie, zamiast wysyłać wszystkie naraz.
4Odczyt pozostałego budżetu
Nigdy nie musisz zgadywać, ile przydziału zostało. Każda mierzona odpowiedź — sukces lub niepowodzenie — zawiera trzy nagłówki: X-Quota-Limit (Twój dzienny limit), X-Quota-Used (ile wywołań zużyłeś dziś) i X-Quota-Reset (moment, w UTC, kiedy licznik się resetuje).
Punkty końcowe sprawdzania spamu odbijają też te same liczby wewnątrz treści odpowiedzi pod obiektem quota, więc możesz odczytać pozostały budżet bez parsowania nagłówków. Użyj ich, by rozkładać własne żądania i ostrzegać się, zanim się skończą.
- X-Quota-Limit — Twój dzienny limit wywołań.
- X-Quota-Used — wywołania zużyte dotychczas dziś.
- X-Quota-Reset — czas resetu w UTC (RFC 3339).
- Odpowiedzi sprawdzania spamu zawierają też obiekt quota z tymi samymi polami.
5Co dzieje się przy 429
Gdy przekroczysz którykolwiek limit, API zwraca HTTP 429 z nagłówkiem Retry-After mówiącym, ile sekund czekać. Dla limitu na minutę Retry-After to około minuta. Dla dziennego przydziału treść niesie kod daily_quota_exceeded plus Twój plan, limit, licznik zużycia, czas resetu i podpowiedź o ulepszeniu, a Retry-After odlicza do północy UTC.
Właściwy sposób obsługi 429 to wycofać się i ponowić po opóźnieniu Retry-After, a nie młócić punkt końcowy. Dobrze zachowujący się klienci odczytują nagłówek i pauzują; klienci, którzy ponawiają natychmiast, po prostu pozostają zablokowani.
- 429 rate_limit_exceeded — wysłałeś zbyt szybko; poczekaj około minutę.
- 429 daily_quota_exceeded — dzień jest wykorzystany; poczekaj do resetu UTC lub dokonaj ulepszenia.
- Zawsze respektuj nagłówek Retry-After przed ponowieniem.