Telm mäter API:et på två sätt: en hastighetsgräns per minut (ett tak för korta toppar) och en daglig kvot (din totala budget för UTC-dygnet). Båda skalar med plan. Varje mätt svar returnerar X-Quota-Limit, X-Quota-Used och X-Quota-Reset så att du alltid vet din återstående budget, och båda gränserna returnerar 429 med ett Retry-After-huvud när de överskrids.
1Två gränser: hastighet per minut och daglig kvot
Det finns två separata tak. Hastighetsgränsen per minut begränsar hur många anrop du kan göra inom en enskild minut, vilket jämnar ut toppar. Den dagliga kvoten är din övergripande budget: den begränsar hur många mätta anrop du kan göra över hela UTC-dygnet.
De är oberoende. Du kan nå gränsen per minut samtidigt som du fortfarande har gott om daglig kvot kvar (du skickar helt enkelt för snabbt), eller tömma din dagliga kvot medan du är väl under gränsen per minut (du har använt upp dagen). Båda returnerar en 429-status, men av olika skäl — kontrollera felkoden i svarskroppen för att skilja dem åt.
- Hastighetsgräns per minut — ett skurtak, nollställs varje minut.
- Daglig kvot — dina totala mätta anrop för dagen, nollställs vid midnatt UTC.
- Kvoten räknas en gång per konto, delad över alla dina nycklar.
2Daglig kvot per plan
Din dagliga kvot är antalet mätta API-anrop du kan göra per UTC-dygn, och den beror på din plan. Räknaren delas över alla dina nycklar och följer den bästa planen bland de grupper du administrerar — utan någon betald prenumeration är du på Free-nivån.
Fönstret är UTC-kalenderdygnet, så din använda räknare nollställs till noll vid midnatt UTC. En batch-spamkontroll kostar ett anrop per objekt i batchen, inte ett anrop för hela anropet.
- Free — 100 anrop per dag.
- Basic — 1 000 anrop per dag.
- Pro — 10 000 anrop per dag.
- Business — 50 000 anrop per dag.
3Hastighetsgräns per minut per plan
Utöver den dagliga kvoten är varje API-nyckel begränsad till ett antal anrop per minut enligt sin plannivå. Detta är en utjämningsgräns: den hindrar en enskild klient från att skicka en enorm topp på en sekund, även när den dagliga budgeten är långt ifrån förbrukad.
Separat gäller breda tak per IP och per konto över hela API:et för att hålla plattformen stabil. Vid normal användning — jämna, avmätta anrop — kommer du aldrig att röra dessa; de utlöses bara vid missbruksartade toppar.
- Free och Basic — 60 anrop per minut.
- Pro — 600 anrop per minut.
- Business — 1 800 anrop per minut.
- Sprid ut anropen istället för att avfyra dem alla på en gång.
4Att läsa din återstående budget
Du behöver aldrig gissa hur mycket kvot som är kvar. Varje mätt svar — framgång eller misslyckande — inkluderar tre huvuden: X-Quota-Limit (din dagliga gräns), X-Quota-Used (hur många anrop du har spenderat idag), och X-Quota-Reset (ögonblicket, i UTC, när räknaren nollställs).
Spamkontroll-endpointerna ekar också samma siffror inuti svarskroppen under ett quota-objekt, så att du kan läsa din återstående budget utan att tolka huvuden. Använd dessa för att styra takten på dina egna anrop och för att varna dig själv innan du tar slut.
- X-Quota-Limit — din dagliga anropsgräns.
- X-Quota-Used — anrop spenderade hittills idag.
- X-Quota-Reset — nollställningstid i UTC (RFC 3339).
- Spamkontroll-svaren inkluderar också ett quota-objekt med samma fält.
5Vad som händer vid 429
När du överskrider någon av gränserna returnerar API:et HTTP 429 med ett Retry-After-huvud som talar om hur många sekunder du ska vänta. För hastighetsgränsen per minut är Retry-After ungefär en minut. För den dagliga kvoten bär svarskroppen en daily_quota_exceeded-kod plus din plan, gräns, använda räknare, nollställningstiden, och ett uppgraderingstips, och Retry-After räknar ner till midnatt UTC.
Rätt sätt att hantera 429 är att backa och försöka igen efter Retry-After-fördröjningen, inte att hamra på endpointen. Välartade klienter läser huvudet och pausar; klienter som fortsätter försöka igen omedelbart förblir helt enkelt blockerade.
- 429 rate_limit_exceeded — du skickade för snabbt; vänta ungefär en minut.
- 429 daily_quota_exceeded — dagen är förbrukad; vänta till UTC-nollställningen eller uppgradera.
- Respektera alltid Retry-After-huvudet innan du försöker igen.