Limiti di frequenza

We use safeguards against bursts of incoming traffic to maximize API stability. If you send many requests in quick succession, you might receive 429 error responses.

API limiters

We enforce several API limiters, including rate and concurrency limiters. Treat limits as maximums and avoid unnecessary load. To prevent abuse, we might reduce your limits. For advice on handling 429 errors, see Handling limiting gracefully. If you see a rise in rate-limited requests, contact Stripe Support.

Request a limit increase for high-traffic applications through Stripe Support. If you request a large increase, contact Stripe Support at least 6 weeks in advance.

Rate limiter

Il limitatore di velocità di base limita il numero di richieste API al secondo come segue:

• Modalità live: 100 operazioni
• Sandbox: 25 operations

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.

• Payment Intents API: 1000 update operations per PaymentIntent, per hour.
• Files API: 20 read operations and 20 write operations per second.
• Search API: 20 read operations per second.
• API Subscriptions:
  • 10 new invoices per subscription, per minute.
  • 20 new invoices per subscription, per day.
  • 200 quantity updates per subscription, per hour.
• Create Payout API: 15 requests per second and 30 concurrent requests per merchant.
• Connect: Platforms can create up to 5 accounts per second in sandbox and 30 accounts per second in live mode.
• Issuing: Card creation has rate limits that depend on the country and business’s industry.

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.

Rate limited requests

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

Concurrency limiter

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.

Common causes and mitigations

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

• A sudden increase in charge volume, such as a flash sale, might result in rate limiting. We try to set our rates high enough that legitimate payment traffic never exceeds the limits, but if you suspect that an upcoming event might push you over the limits listed above, contact Stripe Support.

Handle limiting

Watch for 429 status codes and implement a retry mechanism to handle rate limiting. Follow an exponential backoff schedule to reduce request volume when necessary, and add randomness to the backoff schedule to avoid a thundering herd effect.

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.

Object lock timeouts

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.

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:

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.

Load testing

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

API read request allocations

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:

• Your account’s read API requests must not exceed an average of 500 per transaction. For example, if you process 100 transactions in 30 days, you must not exceed 50,000 read API requests during that period.

• 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 per i dati
• Prodotti per la reportistica
• Prodotti per le imposte

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.