Rate limit (limite di frequenza)

I fornitori fissano limiti per ragioni semplici. La capacità è finita e condivisa, quindi uno script impazzito non deve rallentare tutti gli altri. I limiti contengono anche i costi e fermano abusi, come una chiave rubata usata per inondare un servizio. Senza di essi, un errore in un ciclo potrebbe inviare migliaia di chiamate in un minuto. Pensa a un fornaio che serve una fila: lasciare che un cliente compri tutte le pagnotte nel primo minuto è ingiusto verso gli altri, quindi il fornaio mette un tetto a ciascuno, e un buon limite è solo una quota equa scritta come numero.

I limiti hanno più forme. Un limite breve al minuto assorbe i picchi. Uno più lungo, al giorno, circoscrive l’uso totale, o come finestra fissa che si azzera a un’ora stabilita o come finestra scorrevole che guarda sempre all’indietro sull’ultimo tratto di tempo. Alcuni servizi contano le richieste, altri i token, e alcuni limitano anche quante chiamate possono girare nello stesso momento. I limiti dipendono spesso dal piano, quindi un livello superiore ottiene un tetto più alto.

Gestire bene un limite è un piccolo mestiere. Leggi l’intestazione Retry-After quando c’è e aspetta quel tempo. Altrimenti riprova con un ritardo esponenziale e un po’ di casualità, e mai in un ciclo serrato. Riduci il numero di chiamate mettendo in cache le risposte e raggruppando il lavoro, e distribuisci il carico nel tempo. Ricorda che un rate limit non è un limite di spesa: restare senza saldo è un errore diverso, e il rimedio è un altro. Le librerie spesso incapsulano questa logica al posto tuo, riprovando con garbo e facendo pause tra un tentativo e l’altro; se scrivi un client tuo, registra ogni 429 con data e ora per capire se a causarlo siano picchi improvvisi o un carico costante.

La documentazione dell’API di NeverNo fissa la regola. Ogni account ha un numero di richieste API ogni 24 ore scorrevoli, secondo il piano. Oltre quel numero, le chiamate ricevono un 429 con il codice rate_limited finché la finestra non avanza. Si applica anche un breve limite al minuto, e allora il 429 arriva con un’intestazione Retry-After. Ogni chiamata conta come una richiesta, qualunque sia il numero di token o immagini, mentre l’endpoint che conta i token non viene conteggiato. Poiché la finestra è scorrevole, la capacità torna gradualmente man mano che le vecchie chiamate scadono, e non tutta insieme a mezzanotte.

I numeri esatti per piano sono nella tabella della documentazione dell’API, e non li ripetiamo qui perché questa pagina non diventi mai obsoleta. Finire i crediti è un caso diverso: l’API risponde 402 con insufficient_credits. L’abbonamento Dev usa il limite di richieste di Pro+. Poiché la documentazione è l’unica fonte dei numeri, uno script dovrebbe leggere da lì il tetto invece di fissarlo a caso, e trattare un aumento improvviso di errori 429 come un segnale per rallentare e mettere in coda il lavoro.