Limiti di frequenza

Limiti di frequenza API e loro utilizzo.

L’API Stripe utilizza diversi meccanismi di protezione per evitare gli aumenti improvvisi di traffico in ingresso e massimizzare la sua stabilità. Se invii molte richieste in rapida successione, potresti ricevere risposte di errore con il codice di stato 429.

Limitatori dell’API

Abbiamo diversi limitatori nell’API, tra cui un limitatore di velocità e un limitatore di concorrenza.

Considera i limiti come massimi e non generare un carico non necessario. Per evitare abusi, potremmo ridurre i limiti.

Per consigli sulla gestione degli errori 429, consulta la sezione Gestire i limiti in modo appropriato. Se noti un aumento improvviso delle richieste con limite di frequenza, contatta l’assistenza Stripe.

Puoi richiedere un aumento del limite per abilitare un’applicazione a traffico elevato contattando l’assistenza Stripe. Se richiedi un aumento significativo, contattaci con almeno 6 settimane di anticipo.

Limitatore di velocità

Il limitatore di velocità di base limita il numero di richieste API al secondo come segue:

Modalità live: 100 operazioni di lettura e 100 operazioni di scrittura
Modalità di test: 25 operazioni di lettura e 25 operazioni di scrittura

Le chiamate a determinate risorse hanno limiti più stringenti e vengono conteggiate anche nei limiti di base. Questi limiti più stringenti si applicano separatamente alla modalità live e alla modalità di test.

API Files: 20 operazioni di lettura e 20 operazioni di scrittura al secondo
API Search: 20 operazioni di lettura al secondo

Le chiamate all’endpoint degli eventi del contatore in modalità live sono soggette a un limite di velocità separato e non vengono conteggiate nei limiti di base. Il limite è di 1000 chiamate al secondo per account Stripe. In modalità di test, le chiamate all’endpoint degli eventi del contatore vengono conteggiat nei limiti di base. Per le piattaforme Connect, anche le chiamate a un account connesso all’endpoint degli eventi del contatore vengono conteggiate nel limite di base.

Limitatore di concorrenza

Il limitatore di concorrenza limita il numero di richieste attive simultanee. I problemi con questo limitatore sono meno comuni che con il limitatore di velocità, ma probabilmente indicano l’esistenza di richieste di lunga durata e con un uso intensivo delle risorse.

Le chiamate all’endpoint degli eventi del contatore sono limitate a una chiamata simultanea per cliente per contatore.

Cause più frequenti e mitigazioni

La limitazione degli invii può verificarsi in condizioni diverse, ma è più frequente nei seguenti scenari:

L’esecuzione di un volume elevato di richieste a intervalli ravvicinati può causare la limitazione della velocità. Questa situazione spesso si verifica nell’ambito di un’operazione di analisi o di migrazione. Quando esegui queste attività, cerca di controllare la velocità delle richieste sul lato client (consulta Gestire i limiti in modo appropriato).
L’invio di numerose richieste di lunga durata può attivare la limitazione della velocità. Le richieste non utilizzano tutte la stessa quantità di risorse sui server di Stripe. Le richieste a elevato utilizzo di risorse tendono a durare più a lungo e rischiano di causare il rifiuto di nuove richieste da parte del limitatore di concorrenza. I requisiti di risorse variano notevolmente, ma in genere le richieste di elenchi e quelle che includono espansioni utilizzano più risorse e la loro esecuzione richiede più tempo. Ti consigliamo di analizzare la durata delle richieste dell’API Stripe e controllare i timeout per cercare di individuare quelle che sono inaspettatamente lente.
Un aumento improvviso del volume degli addebiti, come nel caso di una vendita lampo, potrebbe causare la limitazione della velocità. Cerchiamo di impostare limiti di velocità sufficientemente elevati in modo che il traffico di pagamenti legittimi non superi mai i limiti. Tuttavia, se sospetti che un evento comporti il superamento di tali limiti, contatta l’assistenza Stripe.

Gestire i limiti in modo appropriato

Una tecnica di base per gestire in modo appropriato le limitazioni con le integrazioni è verificare la presenza di errori con codice di stato 429 e creare un meccanismo per nuovi tentativi con backoff esponenziale per ridurre il volume delle richieste quando necessario. Ti consigliamo anche di applicare un certo livello di casualità nel backoff per evitare un effetto di reazione di massa.

Dato che puoi ottimizzare le singole richieste solo in misura limitata, per affrontare il problema in modo ancora più sofisticato puoi controllare il traffico verso Stripe a livello globale e ridurlo se rilevi una limitazione sostanziale della velocità. A tal fine, viene utilizzata di frequente una tecnica simile a un algoritmo di limitazione della velocità di tipo token bucket sul lato client. Sono disponibili implementazioni per token bucket pronte all’uso e mature in quasi tutti i linguaggi di programmazione.

Timeout di blocco degli oggetti

Nelle integrazioni possono verificarsi errori con stato HTTP 429, codice lock_timeout e il seguente messaggio:

In questo momento non è possibile accedere a questo oggetto perché un’altra richiesta API o processo Stripe vi stanno accedendo. Se l’errore viene visualizzato in maniera intermittente, ripeti la richiesta. Se l’errore viene visualizzato frequentemente durante più richieste simultanee a un singolo oggetto, prova a effettuare richieste in modo sequenziale o a una velocità inferiore.

L’API Stripe blocca gli oggetti in alcune operazioni per evitare eventuali interferenze nei carichi di lavoro simultanei e risultati incoerenti. L’errore sopra menzionato è causato da una richiesta che cerca di acquisire un blocco già utilizzato altrove e in scadenza dopo che non è stato possibile acquisirlo in tempo.

I timeout di blocco hanno cause diverse dalla limitazione della velocità, ma le misure da prendere per questi due problemi sono simili. Come per gli errori di limitazione della velocità, consigliamo di eseguire nuovi tentativi con backoff esponenziale (consulta Gestire le limitazioni in modo appropriato). Tuttavia, a differenza degli errori di limitazione della velocità, i meccanismi dei nuovi tentativi automatici integrati negli SDK di Stripe eseguiranno un nuovo tentativo per gli errori 429 causati dai timeout di blocco:

I conflitti di blocco sono causati da accessi simultanei su oggetti correlati. Per ridurre notevolmente questo problema, le integrazioni possono verificare che le mutazioni sullo stesso oggetto vengano messe in coda ed eseguite in modo sequenziale. Le operazioni simultanee sull’API vengono comunque accettate, ma verifica che le operazioni simultanee vengano eseguite solo su oggetti unici. Potresti riscontrare anche conflitti di blocco causati da un processo interno di Stripe in background. Questa situazione si verifica raramente, ma dato che è al di fuori del controllo dell’utente, consigliamo di fare in modo che tutte le integrazioni possano inviare di nuovo le richieste.

Test del carico

Quando gli utenti preparano una campagna di vendita importante, di solito verificano il carico sul sistema con l’API Stripe in modalità di test. In genere scoraggiamo l’utilizzo di questa modalità perché i limiti dell’API sono inferiori in modalità di test e di conseguenza è probabile che il test di carico raggiunga i limiti che l’integrazione non raggiungerebbe in produzione. Inoltre la modalità di test non è perfettamente equivalente alle chiamate API in modalità live e questo può essere in qualche modo fuorviante. Ad esempio, la creazione di un addebito in modalità live invia una richiesta a un gateway di pagamento. In modalità di test, questa richiesta sarebbe fittizia e i profili di latenza sarebbero quindi molto diversi.

In alternativa, ti consigliamo di creare le integrazioni in modo tale che dispongano di un sistema configurazione per simulare le richieste inviate all’API Stripe attivabile per i test di carico. Per ottenere risultati realistici, deve simulare la latenza andando in modalità sospensione per un periodo di tempo determinato in base ai campionamenti della durata delle chiamate API Stripe in modalità live dal punto di vista dell’integrazione.

Allocazioni delle richieste API di lettura

Stripe fornisce l’accesso alle sue richieste API di lettura (GET) per facilitare un’attività di ricerca ragionevole relativa alle integrazioni di pagamento. Per massimizzare la qualità del servizio per tutti gli utenti, Stripe fornisce le seguenti allocazioni per le richieste di lettura in base al numero di transazioni:

Le richieste API di lettura non devono superare un rapporto medio di 500 richieste per transazione per un account. Ad esempio, se un account elabora 100 transazioni in un periodo di 30 giorni, non dovrebbero superare le 50.000 richieste API di lettura nello stesso periodo.
Quando utilizzi Connect, una piattaforma e i relativi account connessi dispongono di autorizzazioni API di lettura distinte:
- Ogni account connesso dispone di una allocazione di richieste che avvia (500 richieste per transazione).
- Le piattaforme Connect utilizzano un’allocazione separata per effettuare richieste di lettura per conto dei loro account connessi utilizzando la chiave API privata o i token di accesso OAuth. Questa allocazione è anche di 500 richieste per transazione in base al conteggio aggregato delle transazioni in tutti gli account connessi.
I rapporti vengono misurati ogni 30 giorni su base continua.
Ogni account, indipendentemente dal numero di transazioni, ha un’allocazione minima di 10.000 richieste di lettura al mese.
Le richieste API di scrittura non hanno limiti di allocazione.

Le chiamate ai seguenti endpoint API sono escluse dai limiti di allocazione sopra menzionati:

Per ridurre il volume delle richieste API, ti consigliamo di utilizzare Stripe Data Pipeline per esportare tutti i dati dell’API nel database o provider locale.

Filtra le richieste per limitare le chiamate impaginate

Alcuni endpoint dell’elenco restituiscono più pagine di risultati e potrebbero richiedere più richieste per restituire il set completo di oggetti API per un’operazione di elenco. Applica i filtri quando possibile per restringere i risultati dell’elenco.