Guida alle quote e al rate limiting

FedEx riceve migliaia di richieste API ogni giorno. Utilizziamo tre meccanismi di throttling per gestire questo volume così grande. Le quote, i rate limit e le soglie sono stati stabiliti per allocare le risorse di FedEx in modo efficace ed efficiente.

Le quote sono definite per organizzazione e per progetto API.

Quote per organizzazione

La quota di transazione è il numero massimo di richieste API consentite per un'organizzazione in un giorno. Ciò significa che i consumatori API devono considerare il numero totale di richieste API avviate per tutti i progetti in una sola organizzazione. Ogni richiesta vale quanto le altre, indipendentemente dal volume di dati restituiti nella risposta dell'API FedEx.

Esempio: un'organizzazione ha una quota di 500.000 richieste API al giorno. Se un'organizzazione raggiunge le 500.000 richieste inviate entro le prime ore della giornata, avrà raggiunto la sua quota. Per il resto della giornata viene restituito il codice di errore "429 – Troppe richieste – Quota giornaliera di transazioni superata. Vi invitiamo a riprovare dopo le 00:00 GMT" per ogni richiesta fino al giorno successivo.

Quote per progetto API

Questa quota viene applicata a due livelli diversi: progetto e funzionalità.

Cosa intendiamo per funzionalità?

Ogni API è raggruppata in base alle funzionalità che fornisce. Ogni gruppo di funzionalità è un insieme di uno o più endpoint. Ad esempio, la funzionalità di monitoraggio API ha 6 endpoint API mentre la funzionalità di convalida indirizzo ha solo 1 endpoint API.

Il limite di quota predefinito per funzionalità per progetto (PCPP - Per Capability Per Project) per la funzionalità di monitoraggio è di 100.000 richieste al giorno. Ciò significa che quando il traffico da uno qualsiasi dei progetti all'interno di un'organizzazione verso uno qualsiasi dei 6 endpoint nella funzionalità di monitoraggio supera questo limite, vi invieremo un errore "429 - Troppe richieste" fino alla fine della giornata. Ciò si applica a tutte le richieste di monitoraggio successive per uno qualsiasi dei 6 endpoint.

Esempio: se un progetto ha un limite di 100.000 richieste per funzionalità di monitoraggio (con 6 endpoint), il numero totale di transazioni per tutti e 6 gli endpoint verrà conteggiato fino al limite di 100.000. Se il vostro progetto supera quel limite, tutte le transazioni di monitoraggio successive riceveranno un codice di errore "429 – Troppe richieste – Quota giornaliera di transazioni superata" per il resto della giornata fino alle 00:00 GTM.

Rate limit

Ogni progetto ha un limite di 1.400 transazioni ogni 10 secondi. Le restrizioni di throttling vengono applicate se le transazioni eseguite nell'arco di 10 secondi superano questo limite.

Se questo limite viene raggiunto nei primi secondi, tutte le transazioni eseguite nei secondi restanti di quella finestra di 10 secondi sono soggette al throttling. Durante questo periodo di throttling viene restituito un codice di errore del tipo "429 – Too many requests".

Se FedEx riceve 1.400 richieste nei primi 2 secondi, tutte le transazioni eseguite negli 8 secondi successivi vengono limitate e viene visualizzato il messaggio di errore "429 – Troppe richieste – Abbiamo ricevuto troppe richieste in un breve intervallo di tempo. Vi invitiamo ad attendere prima di riprovare".

Allo scadere dei 10 secondi, le restrizioni di throttling vengono revocate e un altro contatore inizia a monitorare il numero di richieste nei 10 secondi successivi.

Soglie

Le soglie vengono applicate a livello di indirizzo IP per rendere resiliente il processo di autorizzazione API di FedEx. Questo meccanismo si applica unicamente al servizio di generazione di token di autenticazione. Esistono due tipi di soglie:

1. soglia di burst: 3 richieste al secondo, ininterrottamente, per un periodo di 5 secondi.
2. soglia media: 1 richiesta al secondo, ininterrottamente, per un periodo di 2 minuti.

• Quando un indirizzo IP pubblico viola uno di questi limiti di soglia, viene penalizzato per 10 minuti e tutte le ulteriori richieste durante tale periodo ricevono in risposta il codice di stato "403 Accesso negato"
• Se i consumatori API continuano a violare i limiti di soglia durante questo periodo di penalità, il tempo di penalità viene esteso. Gli utenti API possono mettere fine al periodo di penalità non violando il limite di soglia per i successivi 10 minuti
• I meccanismi di soglia si basano sull'indirizzo IP pubblico dell'utente. Se un utente imposta 10 istanze di macchine virtuali con un IP pubblico, tutte le richieste provenienti da quell'indirizzo IP vengono conteggiate ai fini del limite di soglia

Gestione del traffico

Ognuno dei tre seguenti meccanismi tratta un aspetto specifico della gestione del traffico:

• Le quote vengono applicate a livello di organizzazione: il traffico combinato generato da tutte le API all'interno di un'organizzazione è soggetto a questa quota di transazioni.

• Le quote vengono applicate a livello di progetto: il traffico combinato generato per una funzionalità API all'interno di un progetto è soggetto a questa quota di transazioni.

• I rate limit sono applicati a livello di progetto: il traffico combinato generato da tutte le API all'interno di un progetto è soggetto a questo limite.

• Le soglie vengono applicate a livello di indirizzo IP.

Nota: FedEx può ridurre i limiti di uno qualsiasi dei meccanismi di throttling sopra indicati per prevenire qualsiasi abuso, uso improprio o eccessivo. FedEx si riserva la facoltà di modificare l'allocazione senza preavviso al fine di mantenere un accesso equo tra i consumatori API e di allocare le risorse FedEx in modo efficace ed efficiente.

Domande frequenti

Ai fini della quota vengono conteggiate tutte le transazioni API di un'organizzazione provenienti da diversi progetti?
La quota viene applicata a livello di organizzazione. All'interno di un'organizzazione, si possono avere uno o più progetti e, all'interno di ogni progetto, si possono avere una o più API. Pertanto, ai fini della quota giornaliera viene conteggiato il traffico combinato generato da tutte le API di diversi progetti, tutti appartenenti alla stessa organizzazione.

Se viene restituito lo stesso errore 429 sia per una violazione della quota che per una violazione del rate limit, come posso individuare il tipo di violazione in cui sono incorso?
È possibile individuare la violazione leggendo il messaggio di errore.

Qual è la soluzione per una violazione del limite di soglia?
Un token OAuth è valido per un'ora. Suggeriamo ai consumatori di API di utilizzare questo token per l'intera ora e di richiederne uno nuovo solo alla scadenza del precedente.

Qual è un esempio di superamento del limite di soglia?
Le finestre di osservazione per la soglia di burst e per la soglia media sono rispettivamente di 5 e 2 secondi. Durante una di queste finestre, se uno dei due limiti di soglia viene violato da un indirizzo IP, viene imposta una penalità di soglia.

Esempio: se un indirizzo IP effettua 3 richieste al secondo per 2 secondi, seguito da una frequenza di richieste sotto le 3 al secondo, la soglia di burst non viene violata. Tuttavia, se un indirizzo IP effettua 3 richieste al secondo ininterrottamente per 5 secondi, seguito da 15 richieste in 5 secondi, la soglia di burst di 14 richieste in 5 secondi viene violata.