Telm metert de API op twee manieren: een ratelimiet per minuut (een burstplafond) en een dagelijks quotum (je totale budget voor de UTC-dag). Beide schalen met het plan. Elk gemeterd antwoord geeft X-Quota-Limit, X-Quota-Used en X-Quota-Reset terug zodat je altijd je resterende budget kent, en beide limieten geven 429 met een Retry-After-header wanneer ze worden overschreden.
1Twee limieten: rate per minuut en dagelijks quotum
Er zijn twee afzonderlijke plafonds. De ratelimiet per minuut begrenst hoeveel verzoeken je binnen één enkele minuut kunt doen, waardoor bursts worden afgevlakt. Het dagelijkse quotum is je algehele budget: het begrenst hoeveel gemeterde aanroepen je over de hele UTC-dag kunt doen.
Ze zijn onafhankelijk. Je kunt de limiet per minuut raken terwijl je nog volop dagelijks quotum over hebt (je verstuurt simpelweg te snel), of je dagelijkse quotum uitputten terwijl je ruim onder de limiet per minuut zit (je hebt de dag opgebruikt). Beide geven een 429-status, maar om verschillende redenen — controleer de foutcode in de body om ze te onderscheiden.
- Ratelimiet per minuut — een burstplafond, reset elke minuut.
- Dagelijks quotum — je totale gemeterde aanroepen voor de dag, reset om middernacht UTC.
- Het quotum wordt één keer per account geteld, gedeeld over al je sleutels.
2Dagelijks quotum per plan
Je dagelijkse quotum is het aantal gemeterde API-aanroepen dat je per UTC-dag kunt doen, en het hangt af van je plan. De teller wordt gedeeld over al je sleutels en volgt het beste plan onder de groepen die je beheert — zonder betaald plan zit je op het Free-niveau.
Het venster is de UTC-kalenderdag, dus je gebruiksteller reset naar nul om middernacht UTC. Een batch-spamcontrole kost één aanroep per item in de batch, niet één aanroep voor het hele verzoek.
- Free — 100 aanroepen per dag.
- Basic — 1.000 aanroepen per dag.
- Pro — 10.000 aanroepen per dag.
- Business — 50.000 aanroepen per dag.
3Ratelimiet per minuut per plan
Bovenop het dagelijkse quotum is elke API-sleutel beperkt tot een aantal verzoeken per minuut volgens zijn planniveau. Dit is een afvlakkende limiet: het belet dat één client een enorme piek in één seconde verstuurt, zelfs wanneer het dagbudget nog lang niet op is.
Daarnaast gelden brede plafonds per IP en per account over de hele API om het platform stabiel te houden. Bij normaal gebruik — gestage, gedoseerde verzoeken — raak je deze nooit; ze treden alleen in werking bij pieken door misbruik.
- Free en Basic — 60 verzoeken per minuut.
- Pro — 600 verzoeken per minuut.
- Business — 1.800 verzoeken per minuut.
- Spreid verzoeken uit in plaats van ze allemaal tegelijk af te vuren.
4Je resterende budget lezen
Je hoeft nooit te gissen hoeveel quotum er over is. Elk gemeterd antwoord — succes of mislukking — bevat drie headers: X-Quota-Limit (je dagelijkse limiet), X-Quota-Used (hoeveel aanroepen je vandaag hebt besteed) en X-Quota-Reset (het moment, in UTC, waarop de teller reset).
De spam-check-endpoints echoën dezelfde getallen ook binnen de responsbody onder een quota-object, zodat je je resterende budget kunt lezen zonder headers te parsen. Gebruik deze om je eigen verzoeken te doseren en jezelf te waarschuwen voordat je zonder komt te zitten.
- X-Quota-Limit — je dagelijkse aanroeplimiet.
- X-Quota-Used — vandaag tot nu toe bestede aanroepen.
- X-Quota-Reset — resettijd in UTC (RFC 3339).
- De spam-check-antwoorden bevatten ook een quota-object met dezelfde velden.
5Wat er gebeurt bij 429
Wanneer je een van beide limieten overschrijdt, geeft de API HTTP 429 met een Retry-After-header die je vertelt hoeveel seconden je moet wachten. Voor de ratelimiet per minuut is Retry-After ongeveer een minuut. Voor het dagelijkse quotum draagt de body een daily_quota_exceeded-code plus je plan, limiet, gebruiksaantal, de resettijd en een upgrade-hint, en telt Retry-After af naar middernacht UTC.
De juiste manier om 429 te verwerken is terugschakelen en opnieuw proberen na de Retry-After-vertraging, niet het endpoint bestoken. Nette clients lezen de header en pauzeren; clients die meteen blijven herhalen blijven simpelweg geblokkeerd.
- 429 rate_limit_exceeded — je verstuurde te snel; wacht ongeveer een minuut.
- 429 daily_quota_exceeded — de dag is opgebruikt; wacht tot de UTC-reset of upgrade.
- Respecteer altijd de Retry-After-header voordat je opnieuw probeert.