Limiti di frequenza
Ogni richiesta viene contata su una finestra fissa di 60 secondi. Quale contatore si applica dipende da come ti autentichi: le chiavi API hanno il budget più alto, le sessioni autenticate uno generoso, il traffico anonimo uno piccolo. Quando il budget è finito, l'API risponde 429 e ti dice quanto aspettare.
I tre contatori
Il limitatore sceglie esattamente un contatore per richiesta. I limiti qui sotto sono quelli predefiniti; chi gestisce il servizio può cambiarli, quindi leggi gli header della risposta invece di scrivere i numeri nel codice.
apiKey | per chiave API | 1000 req / min |
authenticated | per utente (sessione) | 600 req / min |
anonymous | per IP del client | 30 req / min |
I percorsi di liveness e di documentazione (/health, /meta/version, /docs e /openapi) non vengono mai limitati.
Header della risposta
Ogni rotta soggetta a limite dichiara nella risposta la regola che applica:
X-RateLimit-Limit | Richieste consentite nella finestra corrente per il tuo contatore. |
X-RateLimit-Window-Seconds | Durata della finestra in secondi (60). |
X-RateLimit-Bucket | Quale contatore è stato applicato: anonymous, authenticated o apiKey. |
Retry-After | Solo sui 429: quanti secondi aspettare prima di riprovare. |
Le risposte andate a buon fine portano anche le varianti per contatore, con il nome in coda: per esempio X-RateLimit-Remaining-apiKey (richieste rimaste nella finestra) e X-RateLimit-Reset-apiKey (secondi che mancano al reset della finestra).
La risposta 429
Una richiesta fermata dal limite restituisce il formato di errore standard con il codice stabile RATE_LIMITED. Ragiona sul codice, mostra il messaggio.
{ "error": { "code": "RATE_LIMITED", "message": "ThrottlerException: Too Many Requests", "traceId": "01JGME0Z4E8B3T3Y5F0V9K2QRD" }}Riprovare con backoff
Rispetta Retry-After quando c'è e, altrimenti, usa un backoff esponenziale. Quando ripeti una richiesta che modifica dati, abbinale un'Idempotency-Key: così una ripetizione non può mai creare un duplicato.
async function callWithRetry(request, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await request(); if (res.status !== 429 || attempt === maxRetries) return res; const seconds = Number(res.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); }}Dove siamo più severi
- Gli endpoint IA (chat, scontrini, voce, export) aggiungono un secondo limite legato a utente e famiglia: di default un limite di picco di 10 richieste al minuto e uno continuativo di 200 all'ora.
- Gli endpoint di autenticazione sotto /auth/* hanno un limitatore anti-forza-bruta a parte: 10 tentativi per IP al minuto e 5 per account, con un blocco esponenziale fino a un'ora, che risponde 429 con il codice TOO_MANY_REQUESTS.
- Chi gestisce il servizio può regolare tutti i limiti. Considera come fonte di verità gli header della risposta, non i numeri di questa pagina.