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
Sandbox: 25 operazioni

Le chiamate alle singole risorse hanno limiti più stringenti e vengono conteggiate anche nei limiti globali. Gli endpoint dell’API hanno un limite predefinito di 25 richieste al secondo. Stripe può aumentare i limiti di frequenza per account specifici in base all’utilizzo.

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 frequenza separato e non vengono conteggiate ai fini dei limiti di base. Il limite è di 1000 chiamate al secondo per account Stripe. In una sandbox, le chiamate all’endpoint degli eventi del contatore vengono conteggiate ai fini del limite di base. Per le piattaforme Connect, anche le chiamate su un account connesso all’endpoint degli eventi del contatore vengono conteggiate ai fini del limite di base.

Richieste con limite di frequenza

Le richieste con limite di frequenza restituiscono l’intestazione Stripe-Rate-Limited-Reason con valori che indicano il limite di frequenza superato dalla richiesta. I valori possibili per questa intestazione sono:

global-concurrency: le richieste hanno superato il limite di concorrenza globale. Per evitare questo problema, invia un numero minore di richieste simultanee.
global-rate: le richieste hanno superato il limite di frequenza globale. Per evitare questo problema, invia le richieste a una frequenza inferiore.
endpoint-concurrency: le richieste a questo endpoint dell’API specifico hanno superato il limite di concorrenza. Per evitare questo problema, invia un numero minore di richieste simultanee a questo ebdpoint specifico.
endpoint-rate: le richieste a questo endpoint dell’API specifico hanno superato il limite di frequenza. Per evitare questo problema, invia le richieste a questo endpoint a una frequenza inferiore.
resource-specific: hai raggiunto un limite di frequenza relativo a una risorsa dell’API specifica. Per ulteriori informazioni, fai riferimento alla documentazione relativa a tale risorsa.

Se una richiesta restituisce un codice di stato 429 senza queste intestazioni, non è stato causato da un limitatore di frequenza (ad esempio, potrebbe essere un timeout di blocco).

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 potrebbero verificarsi errori con stato HTTP 429, codice lock_timeout e il seguente messaggio:

A causa di un’altra richiesta API o di un processo Stripe attivo, non è possibile accedere a questo oggetto in questo momento. Se l’errore viene visualizzato in maniera intermittente, ripeti la richiesta. Se l’errore viene visualizzato di frequente 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

È prassi comune che gli utenti preparino i sistemi per eventi di vendita importanti eseguendo test di carico con l’API di Stripe in un ambiente sandbox. Tuttavia, questa pratica è generalmente sconsigliata poiché i limiti API inferiori in sandbox possono portare il test di carico a raggiungere soglie che non si verificherebbero in produzione. Inoltre, una sandbox non replica fedelmente le chiamate API reali. Ad esempio, la creazione di un addebito in modalità live invia una richiesta a un gateway di pagamento che viene simulata in una sandbox, generando profili di latenza significativamente 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.