Telm misura l’API in due modi: un limite di frequenza al minuto (un tetto per i picchi) e una quota giornaliera (il Suo budget totale per la giornata UTC). Entrambi scalano con il piano. Ogni risposta misurata restituisce X-Quota-Limit, X-Quota-Used e X-Quota-Reset così conosce sempre il budget residuo, ed entrambi i limiti restituiscono 429 con un header Retry-After quando vengono superati.
1Due limiti: frequenza al minuto e quota giornaliera
Ci sono due tetti separati. Il limite di frequenza al minuto limita quante richieste può fare in un singolo minuto, appianando i picchi. La quota giornaliera è il Suo budget complessivo: limita quante chiamate misurate può fare nell’intera giornata UTC.
Sono indipendenti. Può raggiungere il limite al minuto pur avendo ancora molta quota giornaliera residua (sta semplicemente inviando troppo in fretta), oppure esaurire la quota giornaliera restando ben al di sotto del limite al minuto (ha consumato la giornata). Entrambi restituiscono uno stato 429, ma per ragioni diverse — controlli il codice di errore nel corpo per distinguerli.
- Limite di frequenza al minuto — un tetto per i picchi, si azzera ogni minuto.
- Quota giornaliera — il totale delle Sue chiamate misurate per la giornata, si azzera a mezzanotte UTC.
- La quota è conteggiata una volta per account, condivisa tra tutte le Sue chiavi.
2Quota giornaliera per piano
La Sua quota giornaliera è il numero di chiamate API misurate che può fare per giornata UTC, e dipende dal Suo piano. Il contatore è condiviso tra tutte le Sue chiavi e segue il piano migliore tra i gruppi che amministra — senza alcun abbonamento a pagamento, è sul livello Free.
La finestra è la giornata di calendario UTC, quindi il Suo contatore usato si azzera a mezzanotte UTC. Un controllo spam in batch costa una chiamata per elemento del batch, non una chiamata per l’intera richiesta.
- Free — 100 chiamate al giorno.
- Basic — 1.000 chiamate al giorno.
- Pro — 10.000 chiamate al giorno.
- Business — 50.000 chiamate al giorno.
3Limite di frequenza al minuto per piano
Oltre alla quota giornaliera, ogni chiave API è limitata a un numero di richieste al minuto in base al livello del suo piano. Questo è un limite di appianamento: impedisce a un singolo client di inviare un enorme picco in un secondo, anche quando il budget giornaliero è ben lontano dall’essere speso.
Separatamente, ampi tetti per IP e per account si applicano all’intera API per mantenere stabile la piattaforma. Nell’uso normale — richieste costanti e cadenzate — non li toccherà mai; scattano solo su picchi abusivi.
- Free e Basic — 60 richieste al minuto.
- Pro — 600 richieste al minuto.
- Business — 1.800 richieste al minuto.
- Distribuisca le richieste invece di scagliarle tutte in una volta.
4Leggere il budget residuo
Non deve mai indovinare quanta quota resta. Ogni risposta misurata — riuscita o fallita — include tre header: X-Quota-Limit (il Suo limite giornaliero), X-Quota-Used (quante chiamate ha speso oggi) e X-Quota-Reset (il momento, in UTC, in cui il contatore si azzera).
Gli endpoint di controllo spam ripetono anche gli stessi numeri all’interno del corpo della risposta sotto un oggetto quota, così può leggere il Suo budget residuo senza analizzare gli header. Li usi per cadenzare le Sue richieste e avvertirsi prima di esaurirle.
- X-Quota-Limit — il Suo limite giornaliero di chiamate.
- X-Quota-Used — chiamate spese finora oggi.
- X-Quota-Reset — orario di azzeramento in UTC (RFC 3339).
- Le risposte di controllo spam includono anche un oggetto quota con gli stessi campi.
5Cosa succede al 429
Quando supera uno dei due limiti, l’API restituisce HTTP 429 con un header Retry-After che Le indica quanti secondi attendere. Per il limite di frequenza al minuto, Retry-After è di circa un minuto. Per la quota giornaliera, il corpo trasporta un codice daily_quota_exceeded più il Suo piano, il limite, il conteggio usato, l’orario di azzeramento e un suggerimento di upgrade, e Retry-After conta alla rovescia fino a mezzanotte UTC.
Il modo giusto di gestire un 429 è arretrare e ritentare dopo il ritardo Retry-After, non martellare l’endpoint. I client ben educati leggono l’header e si fermano; i client che continuano a ritentare immediatamente restano semplicemente bloccati.
- 429 rate_limit_exceeded — ha inviato troppo in fretta; attenda circa un minuto.
- 429 daily_quota_exceeded — la giornata è esaurita; attenda l’azzeramento UTC o esegua l’upgrade.
- Rispetti sempre l’header Retry-After prima di ritentare.