# Limiti di frequenza

Limiti di frequenza API e loro utilizzo.

Stripe uses rate limiting to maximize API stability and prevent abuse, so treat limits as maximums and avoid unnecessary load.

If you exceed the limits, you get `429 Too Many Requests` HTTP status responses. For advice on handling `429` errors, see [Handling limiting gracefully](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Rate limits

In general, rate limits are measured in API requests per second, per Stripe account. The global rate limit applies to total API usage per account, while some endpoints have additional limits of their own.

| Resource                                                                                                                                                                                                                                                                                                                                   | Limits                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Global API rate limit**                                                                                                                                                                                                                                                                                                                  | - *Live mode* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 requests per second
  - *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 requests per second             |
| Individual API endpoints (unless otherwise noted)                                                                                                                                                                                                                                                                                          | 25 requests per second                                                                                                                                                                                                                                                                                                                                                                                                |
| [Payment Intents API](https://docs.stripe.com/api/payment_intents.md)                                                                                                                                                                                                                                                                      | 1000 update requests per PaymentIntent object, per hour                                                                                                                                                                                                                                                                                                                                                               |
| [Subscriptions API](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                                                                                                                                                                                                                                                              |
| [Files API](https://docs.stripe.com/api/files.md)                                                                                                                                                                                                                                                                                          | - 20 read requests per second
  - 20 write requests per second                                                                                                                                                                                                                                                                                                                                                        |
| [Payouts API](https://docs.stripe.com/api/payouts.md)                                                                                                                                                                                                                                                                                      | - 15 [create](https://docs.stripe.com/api/payouts/create.md) requests per second
  - 30 [concurrent requests](https://docs.stripe.com/rate-limits.md#concurrency-limits) per business                                                                                                                                                                                                                                 |
| *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) accounts, including both:
  - [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md)
  - [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *Live mode* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): Create 30 accounts per second
  - *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): Create 5 accounts per second |
| [Search API](https://docs.stripe.com/search.md#rate-limits)1                                                                                                                                                                                                                                                                               | 20 read requests per second                                                                                                                                                                                                                                                                                                                                                                                           |
| [Issuing](https://docs.stripe.com/issuing.md)                                                                                                                                                                                                                                                                                              | Card creation limits depend on the issuing account’s country and industry.                                                                                                                                                                                                                                                                                                                                            |

1. Consider [Sigma](https://docs.stripe.com/data/sigma.md) or [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) for more efficient options for data-intensive analytics tasks.

## Concurrency limits

Concurrency limits restrict the number of simultaneously active requests, separate from rate limits. Unlike rate limits, which in general reset after one second, the concurrency limit counts how many requests are in progress at any given moment. Hitting concurrency limits is less common than rate limit errors, and typically indicate long-lived or resource-intensive API requests such as list requests or those that include [expansions](https://docs.stripe.com/expand.md).

## Rate-limited responses

Requests that get rate-limited return a `429 Too Many Requests` HTTP status code, and include a `Stripe-Rate-Limited-Reason` header that explains why the request was rate-limited. Possible values for this header are:

| Header value           | Meaning                                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `global-rate`          | Your requests have exceeded the global rate limit. You can prevent this by sending requests at a lower rate.                                                            |
| `endpoint-rate`        | Your requests to this specific API endpoint have exceeded the rate limit. You can prevent this by sending requests to this endpoint at a lower rate.                    |
| `global-concurrency`   | Your requests have exceeded the global concurrency limit. You can prevent this by sending fewer simultaneous requests.                                                  |
| `endpoint-concurrency` | Your requests to this specific API endpoint have exceeded the concurrency limit. You can prevent this by sending fewer simultaneous requests to this specific endpoint. |
| `resource-specific`    | You’ve hit a rate limit related to a specific API resource. Refer to the documentation for that resource for more information.                                          |

If a request returns a `429` status code without these headers, it wasn’t the result of a rate limit. It may be a [lock timeout](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/).

- Issuing many long-lived requests can trigger concurrency limiting. Requests vary in the amount of Stripe server resources they use, and more resource-intensive requests can take longer and run the risk of causing the concurrency limiter to shed new requests. Resource requirements vary widely, but list requests and requests that include [expansions](https://docs.stripe.com/expand.md) generally use more resources and take longer to run. We suggest profiling the duration of Stripe API requests and watching for timeouts to identify unexpectedly slow ones.

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

A more sophisticated approach is to control traffic to Stripe at a global level, and throttle it back if you detect substantial rate limiting. A common technique for controlling API usage is to implement a client-side [token bucket rate-limiting algorithm](https://en.wikipedia.org/wiki/Token_bucket). Token bucket implementations or libraries are available for most programming languages.

## Timeout di blocco degli oggetti

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

> This object cannot be accessed right now because another API request or Stripe process is currently accessing it. If you see this error intermittently, retry the request. If you see this error frequently and are making multiple concurrent requests to a single object, make your requests serially or at a lower rate.

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.

- Ratios are calculated over a rolling 30-day period (the most recent 30 days).

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

To reduce your API request volume, consider using [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) for a complete export of API data to your local database or provider.

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