Limiti di frequenza
Quante richieste puoi inviare, cosa succede se ne invii di più e gli altri limiti da conoscere.
I limiti proteggono tutti quelli che condividono il servizio. I valori predefiniti sono ampi per un uso normale; se ne raggiungi uno, la risposta ti dice esattamente quanto aspettare.
In sintesi
| Limite | Predefinito | Quando lo raggiungi |
|---|---|---|
Scritture per account (createTask, retry, caricamenti …) | 1.000 ogni 10 secondi | 429 con Retry-After |
Letture per account (recordInfo, models, jobs, quote …) | 1.000 ogni 10 secondi | 429 con Retry-After |
| Ticket di caricamento | 1.000 ogni 10 secondi, in aggiunta alle scritture | 429 con Retry-After |
Report di utilizzo (/api/v1/usage) | 30 al minuto per account | 429 con Retry-After |
| Libreria di asset | 60 letture e 30 salvataggi al minuto, più un numero giornaliero di nuovi asset | 429 con Retry-After |
| Qualsiasi richiesta prima della verifica della chiave | 6.000 al minuto per rete | 429 |
| Corpo della richiesta | 2 MiB di JSON | 413 |
| Saldo | Quello che c’è sul tuo account | 40201 |
| Tetti di spesa per chiave | Nessuno, a meno che tu non lo imposti | 40202 |
I limiti si contano per account, non per chiave: creare altre chiavi non li aumenta.
Header di risposta
| Header | Significato |
|---|---|
X-RateLimit-Limit | La tua quota nella finestra attuale |
X-RateLimit-Remaining | Quanto ne resta; arriva anche nelle risposte riuscite, così puoi rallentare in tempo |
Retry-After | Su un 429: secondi da attendere prima di riprovare |
I numeri qui sopra sono predefiniti e possono cambiare; fidati degli header invece di fissarli nel codice.
Com’è fatto un limite
{ "code": 429, "msg": "Too many requests. Retry in a moment", "request_id": "req_…" }Una richiesta oltre il limite viene rifiutata subito — non messa in coda — e non costa nulla.
Come gestirlo
- Aspetta almeno
Retry-Aftersecondi, poi riprova. Aggiungi un po’ di casualità perché un gruppo di client non torni nello stesso istante. - Quando ritenti
createTask, invia lo stessoIdempotency-Key(Idempotenza). - Interroga con calma: ogni pochi secondi per le immagini, ogni 10–15 secondi per i video. Meglio ancora, usa i webhook: non consumano nessuna richiesta.
Tante attività insieme
I limiti di frequenza regolano quanto velocemente invii le richieste, non quante attività girano contemporaneamente. Puoi averne molte in corso; i video lunghi richiedono solo più tempo. Se devi avviare migliaia di attività, distribuisci gli invii nel tempo e lascia che i webhook riportino i risultati.
Ti serve una quota più alta per un lancio o un grosso lotto? Scrivici indicando il volume previsto.