Rate Limiting
Invoicetronic API applica il rate limiting. Quando il limite viene raggiunto, i client ricevono una risposta 429 Too Many Requests fino al reset della finestra temporale.
Limiti globali
I seguenti limiti sono applicati per-utente a tutte le richieste autenticate:
| Periodo | Limite | Reset |
|---|---|---|
| Secondo | 100 richieste | Ogni secondo |
| Minuto | 2000 richieste | Ogni minuto |
| Giorno | 100000 richieste | Giornaliero |
Supponiamo che 2000 richieste colpiscano l'API nella finestra di un minuto, le richieste successive che si verificano in quello stesso minuto verranno bloccate con 429. Quando il minuto termina, la finestra si resetta e l'API riprenderà a soddisfare le richieste.
Limite aggiuntivo sugli endpoint di polling
Gli endpoint di lettura più frequentemente interrogati in polling sono protetti da un limite aggiuntivo per-utente, basato su algoritmo token bucket:
| Parametro | Valore |
|---|---|
| Burst massimo | 200 richieste istantanee |
| Tasso sostenuto | 60 richieste al minuto |
Si applica a tutte le richieste GET verso:
/receive/(lista e dettaglio)/update/(lista e dettaglio)/send/(lista e dettaglio)/log/(lista e dettaglio)/webhookhistory/(lista e dettaglio)
Il meccanismo assorbe senza penalità i burst legittimi, ad esempio durante la paginazione sequenziale di grandi set di risultati (fino a 200 richieste ravvicinate in pochi secondi), ma limita a 60 richieste al minuto il tasso sostenuto nel tempo. Una volta esaurito il burst, le richieste successive ricevono 429 finché il bucket non si rifornisce.
Questo limite è aggiuntivo rispetto a quelli globali: una richiesta deve rientrare sia nei limiti globali sia in quello di polling per essere servita.
Webhook invece di polling
Se stai interrogando frequentemente gli endpoint /receive/ o /update/ per scoprire novità, valuta l'uso dei webhook. I webhook notificano il tuo sistema in tempo reale quando arrivano eventi, eliminando completamente la necessità del polling e riducendo drasticamente il numero di chiamate API.
Header di risposta
Ogni risposta dell'API include i seguenti header relativi al rate limiting:
| Header | Descrizione |
|---|---|
RateLimit-Limit |
Il limite di richieste al secondo più restrittivo (es. 100). |
RateLimit-Policy |
Tutte le finestre di rate limiting attive nel formato limite;w=secondi. Per gli endpoint di polling include anche il frammento 60;w=60;burst=200. |
Esempi di valore di RateLimit-Policy:
- Endpoint generico:
100;w=1, 2000;w=60, 100000;w=86400 - Endpoint di polling:
100;w=1, 2000;w=60, 100000;w=86400, 60;w=60;burst=200
Quando una richiesta viene rifiutata con 429 Too Many Requests, la risposta include anche:
| Header | Descrizione |
|---|---|
Retry-After |
Secondi da attendere prima di riprovare (es. 1). |
Tip
Il tuo client dovrebbe essere preparato a gestire le risposte 429 anche se sono improbabili. Quando ricevi un 429, leggi l'header Retry-After per sapere esattamente quanto tempo attendere prima di riprovare. Non lasciare che il tuo client vada in crash in uno scenario ben noto e documentato come questo; danneggerebbe l'esperienza dell'utente finale.