# Limiti di frequenza Limiti di frequenza API e loro utilizzo. Utilizziamo misure di sicurezza contro i picchi di traffico in entrata per massimizzare la stabilità dell’API. Se invii molte richieste in rapida successione, potresti ricevere risposte di errore `429`. ## Limitatori dell’API Applichiamo diversi limitatori API, inclusi limitatori di frequenza e concorrenza. Considera i limiti come massimi ed evita carichi inutili. Per prevenire abusi, potremmo ridurre i tuoi limiti. Per consigli sulla gestione degli errori `429`, consulta [Gestione elegante dei limiti](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully). Se noti un aumento delle richieste con limite di frequenza, [contatta l’assistenza Stripe](https://support.stripe.com/). Richiedi un aumento del limite per le applicazioni ad alto traffico tramite l’[assistenza Stripe](https://support.stripe.com/). Se richiedi un aumento significativo, [contatta l’assistenza Stripe](https://support.stripe.com/) con almeno 6 settimane di anticipo. ### Limitatore di frequenza Il limitatore di velocità di base limita il numero di richieste API al secondo come segue: - **Modalità live**: 100 operazioni - Operazioni *Sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes): 25 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 Payment Intents](https://docs.stripe.com/api/payment_intents.md): 1000 operazioni di aggiornamento per PaymentIntent, all’ora. - [API Files](https://docs.stripe.com/api/files.md): 20 operazioni di lettura e 20 operazioni di scrittura al secondo. - [API Search](https://docs.stripe.com/search.md#rate-limits): 20 operazioni di lettura al secondo. - [API Subscriptions](https://docs.stripe.com/api/Subscriptions.md): - 10 nuove fatture per abbonamento, al minuto. - 20 nuove fatture per abbonamento, al giorno. - 200 aggiornamenti di quantità per abbonamento, all’ora - [Crea API Payout](https://docs.stripe.com/api/payouts/create.md): 15 richieste al secondo e 30 richieste simultanee per attività. - [Connect](https://docs.stripe.com/connect.md): le piattaforme possono creare fino a 5 account al secondo nella sandbox e 30 account al secondo in modalità live. - [Issuing](https://docs.stripe.com/issuing.md): la creazione di carte ha limiti di frequenza che dipendono dal Paese e dal settore dell’attività. Le chiamate all’[endpoint degli eventi del contatore](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api.md#rate-limits) 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](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api.md#rate-limits) 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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)). - L’emissione di **molte richieste di lunga durata** può attivare la limitazione. Le richieste variano in base alla quantità di risorse del server Stripe che utilizzano e quelle che richiedono più risorse possono richiedere più tempo ed esporsi al rischio che il limitatore di concorrenza elimini le nuove richieste. I requisiti relativi alle risorse variano notevolmente, ma le richieste di elenco e quelle che includono espansioni generalmente utilizzano più risorse e richiedono più tempo per essere eseguite. Ti consigliamo di profilare la durata delle richieste API Stripe e di monitorare 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](https://support.stripe.com/). ## Gestisci la limitazione Controlla i codici di stato `429` e implementa un meccanismo di riprova per gestire la limitazione della frequenza. Segui un programma di backoff esponenziale per ridurre il volume delle richieste quando necessario e aggiungere casualità al programma di backoff per evitare [l’effetto thundering herd](https://en.wikipedia.org/wiki/Thundering_herd_problem). 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](https://en.wikipedia.org/wiki/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 su alcune operazioni in modo che i carichi di lavoro simultanei non interferiscano tra loro e producano risultati incoerenti. L’errore sopra riportato è causato da una richiesta che tenta di acquisire un blocco già detenuto altrove e che va in timeout dopo non essere riuscita ad acquisirlo in tempo. Stripe non elabora queste richieste non riuscite, il che significa che non viene loro assegnato un [ID richiesta](https://docs.stripe.com/api/request_ids.md). 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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)). Tuttavia, a differenza degli errori di limitazione della velocità, i meccanismi dei nuovi tentativi automatici integrati negli [SDK](https://docs.stripe.com/sdks.md) di Stripe eseguiranno un nuovo tentativo per gli errori `429` causati dai timeout di blocco: #### Ruby ```ruby Stripe.max_network_retries = 2 ``` 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 del tuo account non devono superare una media di 500 per transazione. Ad esempio, se elabori 100 transazioni in 30 giorni, non devi superare le 50.000 richieste API di lettura durante tale 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 sono calcolati su un periodo di 30 giorni consecutivi (gli ultimi 30 giorni). - 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: - [Prodotti per i dati](https://docs.stripe.com/stripe-data.md) - [Prodotti per la reportistica](https://docs.stripe.com/stripe-reports.md) - [Prodotti per le imposte](https://docs.stripe.com/tax.md) Per ridurre il volume delle richieste API, ti consigliamo di utilizzare [Stripe Data Pipeline](https://stripe.com/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](https://docs.stripe.com/api/pagination.md) 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.