Panoramica

Che un token venga distribuito tramite Developer Portal, concessione OAuth o il backend degli account che eroga le app di Frame.io, tutte le chiamate API a Frame.io hanno dei limiti di frequenza. I limiti di frequenza si applicano a tutte le richieste API di un singolo utente (indipendentemente dal token o dal metodo di autenticazione utilizzato), vengono esauriti e ricaricati progressivamente e sono riportati nelle intestazioni di ogni richiesta effettuata all’API Frame.io. Ogni endpoint è configurato con limiti specifici, che vanno da un minimo di 10 richieste al minuto fino a 100 richieste al secondo. Le richieste che hanno superato il limite di velocità per un endpoint specifico riceveranno un errore HTTP 429 in risposta.

Esaurimento e ricarica

L’API Frame.io utilizza una strategia di tipo leaky bucket per limitare progressivamente la frequenza. I limiti si aggiornano gradualmente durante l’intervallo di tempo assegnato. In altre parole, non esiste un concetto di cutoff netto dopo il quale i limiti si aggiornano per una risorsa specifica (ovvero strategie di applicazione “fisse” e a “finestra scorrevole”). I limiti rimanenti si aggiornano costantemente a un ritmo relativo al limite e all’intervallo di tempo di una risorsa.

Backoff esponenziale

La strategia che consigliamo per gestire i limiti di frequenza è solitamente chiamata “backoff esponenziale”.

In breve:

• Quando ricevi un errore 429, attiva un periodo di pausa (di solito un secondo)
• Se ricevi un altro errore 429, aumenta esponenzialmente il periodo di attesa fino alla ripresa del funzionamento normale

Intestazioni

Le risposte alle richieste API includeranno sempre le seguenti tre intestazioni che dovrebbero essere utilizzate per limitare le richieste in uscita:

Esempio

L’esempio seguente proviene dalla risposta a GET v2/assets/:id/children per recuperare le risorse figlio di una root del progetto, una cartella o uno stack di versioni). Il limite per quel percorso è di 40 richieste per 60.000 ms (un minuto) e rimangono 39 richieste dopo che ne è stata effettuata una.

x-ratelimit-limit → 40
x-ratelimit-remaining → 39
x-ratelimit-window → 60000

Dettagli

I limiti di frequenza variano notevolmente tra i percorsi delle risorse nell’API Frame.io. Di seguito sono riportati alcuni dettagli selezionati, espressi per leggibilità come risorsa e azione (ad esempio “Risorse — Aggiorna” invece di PUT /assets/:id).

Come regola generale, i percorsi delle risorse che creano nuovi dati sono limitati a 100 chiamate al minuto o meno e i percorsi delle risorse che recuperano elenchi di risorse sono limitati a 200 chiamate al minuto.