Limiti di frequenza
L’API Stripe utilizza diversi meccanismi di protezione per evitare gli aumenti improvvisi di traffico in ingresso e massimizzare la sua stabilità. Gli utenti che inviano molte richieste in rapida successione potrebbero ricevere risposte di errore identificate dal codice di stato 429
. L’API dispone di diversi meccanismi di limitazione, tra cui:
Un limitatore di frequenza, che limita il numero di richieste ricevute dall’API al secondo.
Per la maggior parte delle API, Stripe consente fino a un massimo di 100 operazioni al secondo in lettura e 100 in scrittura in modalità live e 25 operazioni al secondo in modalità di test.
Per l’API Files, Stripe consente fino a un massimo di 20 operazioni al secondo in lettura e 20 in scrittura, sia in modalità live che in modalità di test. I limiti della modalità live e di test sono conteggiati separatamente.
Per l’API Search, Stripe consente fino a un massimo di 20 operazioni al secondo in lettura, il che si applica a tutti gli endpoint di ricerca sia in modalità live che in modalità di test. I limiti della modalità live e di test sono conteggiati separatamente.
Un limitatore di concorrenza, che limita il numero di richieste attive in un determinato momento. Questo meccanismo causa problemi meno frequenti rispetto a quelli del limitatore della velocità delle richieste, ma è più probabile che si verifichino richieste di lunga durata e con un uso intensivo delle risorse.
Considera questi limiti come massimi e non generare carichi in eccesso. 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.
Possiamo ridurre i limiti al fine di evitare abusi, oppure aumentarli per consentire l’utilizzo di applicazioni con traffico elevato. Per richiedere un aumento del limite di invii, contatta l’assistenza. Se richiedi un aumento consistente, contattaci con 6 settimane di anticipo rispetto alla data in cui avrai bisogno dell’aumento del limite di invii.
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 la maggior parte degli utenti non venga mai sottoposta a limitazioni della velocità per traffico di pagamenti legittimo. Tuttavia, se sospetti che un evento comporti il superamento di tali limiti, contatta l’assistenza.
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 nelle librerie client 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.