# Limiti di frequenza

Limiti di frequenza API e loro utilizzo.

Stripe usa i limiti di frequenza per massimizzare la stabilità dell’API ed evitare gli abusi, quindi tratta i limiti come massimali ed evita carichi superflui.

Se superi i limiti, ricevi risposte di stato HTTP `429 Too Many Requests`. Per consigli sulla gestione degli errori `429`, vedi [Gestire i limiti in modo ottimale](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Limiti di frequenza

In generale, i limiti di frequenza sono misurati in richieste API al secondo per ogni account Stripe. Il limite di frequenza globale si applica all’utilizzo totale dell’API per account, mentre alcuni endpoint hanno limiti aggiuntivi propri.

| Risorsa | Limiti |
| --- | --- |
| **Limite di frequenza dell’API globale** | - *Modalità live* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 richieste al secondo
- *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 richieste al secondo |
| Singoli endpoint dell’API (salvo diversa indicazione) | 25 richieste al secondo |
| [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) | 1.000 richieste di aggiornamento per oggetto PaymentIntent all’ora |
| [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 |
| [API Files](https://docs.stripe.com/api/files.md) | - 20 richieste di lettura al secondo
- 20 richieste di scrittura al secondo |
| [API Payouts](https://docs.stripe.com/api/payouts.md) | - 15 richieste di [creazione](https://docs.stripe.com/api/payouts/create.md) al secondo
- 30 [richieste simultanee](https://docs.stripe.com/rate-limits.md#concurrency-limits) per attività |
| Account *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), inclusi entrambi i seguenti:
- [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md)
- [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *Modalità live* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): creazione di 30 account al secondo
- *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): creazione di 5 account al secondo |
| [API Search](https://docs.stripe.com/search.md#rate-limits)1 | 20 richieste di lettura al secondo |
| [Issuing](https://docs.stripe.com/issuing.md) | I limiti di creazione delle carte dipendono dal Paese e dal settore dell’account di Issuing. |

Prendi in considerazione [Sigma](https://docs.stripe.com/data/sigma.md) o [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) per opzioni più efficienti per le attività di analisi ad alta intensità di dati.

## Limiti di simultaneità

I limiti di simultaneità limitano il numero di richieste simultaneamente attive, separatamente dai limiti di frequenza. A differenza dei limiti di frequenza, che in generale si azzerano dopo un secondo, il limite di simultaneità conta quante richieste sono in corso in un dato momento. Raggiungere i limiti di simultaneità è meno comune degli errori sui limiti di frequenza, e di solito indica richieste API di lunga durata o ad alta intensità di risorse, come richieste di elenchi o quelle che includono le [espansioni](https://docs.stripe.com/expand.md).

## Risposte con limiti di frequenza

Le richieste a cui viene applicato un limite di frequenza restituiscono un codice di stato HTTP `429 Too Many Requests` e includono un’intestazione `Stripe-Rate-Limited-Reason` che spiega perché la richiesta è stata limitata. I valori possibili per questa intestazione sono:

| Valore dell’intestazione | Significato |
| --- | --- |
| `global-rate` | Le tue richieste hanno superato il limite di frequenza globale. Puoi evitare questo problema inviando richieste a una frequenza inferiore. |
| `endpoint-rate` | Le tue richieste a questo specifico endpoint dell’API hanno superato il limite di frequenza. Puoi evitare questo problema inviando richieste a questo endpoint a una frequenza inferiore. |
| `global-concurrency` | Le tue richieste hanno superato il limite di simultaneità globale. Puoi evitare questo problema inviando meno richieste simultanee. |
| `endpoint-concurrency` | Le tue richieste a questo specifico endpoint dell’API hanno superato il limite di simultaneità. Puoi evitare questo problema inviando meno richieste simultanee a questo specifico endpoint. |
| `resource-specific` | Hai raggiunto un limite di frequenza relativo a una specifica risorsa API. Per maggiori informazioni consulta la documentazione di quella risorsa. |

Se una richiesta restituisce un codice di stato `429` senza queste intestazioni, non era il risultato di un limite di frequenza. Potrebbe essere un [timeout di blocco](https://docs.stripe.com/rate-limits.md#object-lock-timeouts).

## 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)).

- 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/).

- L’emissione di molte richieste di lunga durata può attivare la limitazione della simultaneità. Le richieste variano in base alla quantità di risorse del server Stripe che utilizzano e le richieste a più alta intensità di risorse possono richiedere più tempo e correre il rischio di far sì che il limitatore di simultaneità elimini nuove richieste. I requisiti di risorse variano ampiamente, ma le richieste di elenchi e le richieste che includono [espansioni](https://docs.stripe.com/expand.md) in genere utilizzano più risorse e richiedono più tempo per l’esecuzione. Suggeriamo di profilare la durata delle richieste di API Stripe e di osservare i timeout per identificare quelle inaspettatamente lente.

## 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).

Un approccio più sofisticato è quello di controllare il traffico verso Stripe a livello globale e ridurlo se rilevi limitazioni di frequenza sostanziali. Una tecnica comune per controllare l’utilizzo dell’API è implementare un [algoritmo per i limiti di frequenza del token bucket](https://en.wikipedia.org/wiki/Token_bucket) lato client. Esistono implementazioni o librerie di token bucket per la maggior parte dei linguaggi di programmazione.

## Timeout di blocco degli oggetti

Nelle integrazioni potrebbero 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 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 dati](https://docs.stripe.com/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, valuta la possibilità di utilizzare [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) per un’esportazione completa dei dati dell’API verso il tuo database o fornitore 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.