Telm contorizează API-ul în două moduri: o limită de rată pe minut (un plafon de vârf) și o cotă zilnică (bugetul dumneavoastră total pentru ziua UTC). Ambele scalează cu planul. Fiecare răspuns contorizat returnează X-Quota-Limit, X-Quota-Used și X-Quota-Reset astfel încât să vă cunoașteți întotdeauna bugetul rămas, iar ambele limite returnează 429 cu un antet Retry-After când sunt depășite.
1Două limite: rata pe minut și cota zilnică
Există două plafoane separate. Limita de rată pe minut plafonează câte cereri puteți face într-un singur minut, netezind vârfurile. Cota zilnică este bugetul dumneavoastră general: plafonează câte apeluri contorizate puteți face pe parcursul întregii zile UTC.
Sunt independente. Puteți atinge limita pe minut având în același timp încă multă cotă zilnică rămasă (pur și simplu trimiteți prea repede) sau puteți epuiza cota zilnică fiind cu mult sub limita pe minut (ați consumat ziua). Ambele returnează un status 429, dar din motive diferite — verificați codul de eroare din corp pentru a le deosebi.
- Limita de rată pe minut — un plafon de vârf, se resetează în fiecare minut.
- Cota zilnică — apelurile dumneavoastră contorizate totale pentru zi, se resetează la miezul nopții UTC.
- Cota este numărată o singură dată per cont, partajată între toate cheile dumneavoastră.
2Cota zilnică în funcție de plan
Cota dumneavoastră zilnică este numărul de apeluri API contorizate pe care le puteți face pe zi UTC și depinde de planul dumneavoastră. Contorul este partajat între toate cheile dumneavoastră și urmează cel mai bun plan dintre grupurile pe care le administrați — fără un abonament plătit, sunteți pe nivelul Free.
Fereastra este ziua calendaristică UTC, deci contorul dumneavoastră de utilizare se resetează la zero la miezul nopții UTC. O verificare de spam în lot costă un apel per element din lot, nu un apel pentru întreaga cerere.
- Free — 100 de apeluri pe zi.
- Basic — 1.000 de apeluri pe zi.
- Pro — 10.000 de apeluri pe zi.
- Business — 50.000 de apeluri pe zi.
3Limita de rată pe minut în funcție de plan
Pe lângă cota zilnică, fiecare cheie API este limitată la un număr de cereri pe minut în funcție de nivelul planului său. Aceasta este o limită de netezire: împiedică un singur client să trimită un vârf uriaș într-o secundă, chiar și când bugetul zilnic este departe de a fi consumat.
Separat, se aplică plafoane largi per IP și per cont pe întregul API pentru a menține platforma stabilă. În utilizarea normală — cereri constante, ritmate — nu le veți atinge niciodată; ele se declanșează doar la vârfuri abuzive.
- Free și Basic — 60 de cereri pe minut.
- Pro — 600 de cereri pe minut.
- Business — 1.800 de cereri pe minut.
- Distribuiți cererile în loc să le lansați pe toate deodată.
4Citirea bugetului dumneavoastră rămas
Nu trebuie niciodată să ghiciți cât din cotă a rămas. Fiecare răspuns contorizat — reușit sau eșuat — include trei anteturi: X-Quota-Limit (limita dumneavoastră zilnică), X-Quota-Used (câte apeluri ați consumat astăzi) și X-Quota-Reset (momentul, în UTC, când se resetează contorul).
Endpoint-urile de verificare a spamului reflectă aceleași numere și în interiorul corpului răspunsului, sub un obiect quota, astfel încât să vă puteți citi bugetul rămas fără a analiza anteturi. Folosiți-le pentru a vă ritma propriile cereri și pentru a vă avertiza înainte de a rămâne fără.
- X-Quota-Limit — limita dumneavoastră zilnică de apeluri.
- X-Quota-Used — apelurile consumate până acum astăzi.
- X-Quota-Reset — momentul de resetare în UTC (RFC 3339).
- Răspunsurile de verificare a spamului includ de asemenea un obiect quota cu aceleași câmpuri.
5Ce se întâmplă la 429
Când depășiți oricare dintre limite, API-ul returnează HTTP 429 cu un antet Retry-After care vă spune câte secunde să așteptați. Pentru limita de rată pe minut, Retry-After este de aproximativ un minut. Pentru cota zilnică, corpul poartă un cod daily_quota_exceeded plus planul dumneavoastră, limita, numărul consumat, momentul de resetare și un indiciu de upgrade, iar Retry-After numără invers până la miezul nopții UTC.
Modul corect de a gestiona 429 este să vă retrageți și să reîncercați după întârzierea Retry-After, nu să bombardați endpoint-ul. Clienții bine comportați citesc antetul și fac pauză; clienții care continuă să reîncerce imediat rămân pur și simplu blocați.
- 429 rate_limit_exceeded — ați trimis prea repede; așteptați aproximativ un minut.
- 429 daily_quota_exceeded — ziua este consumată; așteptați până la resetarea UTC sau faceți upgrade.
- Respectați întotdeauna antetul Retry-After înainte de a reîncerca.