Stripe rate limiting API
Stripe applica rate limiting alle API per garantire stabilità globale del servizio. Conoscere i limiti e implementare correttamente la gestione dei 429 Too Many Requests è essenziale per integrazioni production-grade ad alto volume.
Limiti di base e come scalano
I limiti di default sono 100 read/sec e 100 write/sec in Live mode; in Test mode sono più bassi (25 read/sec, 25 write/sec). I limiti scalano automaticamente con il volume del tuo account; merchant ad alto volume hanno limiti molto più alti. Le chiamate di list paginate (es. customers.list) contano come singola read anche se restituiscono molti record.
Gestione 429 e exponential backoff
Quando superi il limite ricevi HTTP 429 con header Retry-After. La best practice è exponential backoff: retry dopo 1s, poi 2s, poi 4s, fino a 32s max, con jitter random per evitare thundering herd. L'SDK ufficiale Stripe implementa backoff automatico per errori di rete e 5xx, ma 429 deve essere gestito esplicitamente.
Bulk operations e batch API
Per scenarios high-throughput (import bulk customers, mass refund campagna), evita N chiamate singole: 1) Usa Stripe File Upload + Reports per processing offline; 2) Usa expand[] per ridurre round-trip; 3) Bullhost: chiamate parallele con concurrency limit (es. 10 chiamate concurrent); 4) Per Stripe Connect platform, batch operations su account collegati con rate limit per-account. Pattern winning per import 100k customer: split in chunk da 50, parallel concurrency 10, sleep 100ms tra batch. Tempo totale ~30 minuti per 100k, vs 8+ ore con chiamate sequenziali.
Monitoring proattivo e alerting
Setup monitoring per Stripe API: 1) Track 4xx/5xx rate per endpoint con Datadog/Prometheus; 2) Alert su 429 rate > 1% (warning) o > 5% (critical); 3) Latency monitoring p95 (Stripe target < 200ms per chiamate semplici); 4) Webhook delivery success rate (deve essere > 99%, Stripe Dashboard mostra trend). Su alert 429 cronico, contatta Stripe support con dati: timestamp, volume RPS, endpoint. Stripe alza limiti tipicamente entro 24-48h per merchant legittimi. Per produzione critical, mantieni un buffer 30-40% sotto rate limit per gestire spike.
Concurrency control nell'integrazione
Per evitare di saturare rate limit su batch operations: 1) Token bucket lib (es. node-rate-limiter, python-ratelimiter) configurato a 80% del limit Stripe (es. 80 req/s con limit 100); 2) Promise.all con concurrency control (p-limit per Node, asyncio.Semaphore per Python); 3) Queue worker concurrency tuned (max 10 worker simultanei). Esempio Node: const limit = pLimit(10); await Promise.all(items.map(item => limit(() => stripe.customers.create(item)))). Monitoring: log rate-limited request, alert se sustained > 5% del traffico.
Idempotency-Key generation strategy
Idempotency-Key best practice: 1) UUID v4 random per ogni request unique; 2) Deterministic key per retry (es. hash del payload + timestamp arrotondato a 5 min); 3) Per webhook reaction code, use event.id come idempotency_key per chiamate Stripe risultanti; 4) Storage del key per 24h+ per garantire retry consistency. Stripe retains idempotency per 24h - dopo, stessa key è considerata nuova request. Best practice business-critical: log every Idempotency-Key generated per audit. Mai ri-use chiavi vecchie per request nuove (rischio false positive dedup).
Limiti operativi e response time
Stripe API performance media: p50 latency 100ms, p95 300ms, p99 1s globalmente. Da Italia verso api.stripe.com (region EU): tipicamente 50-150ms p50. Per latency-sensitive operation (es. checkout in-app), considera: 1) HTTP/2 connection keepalive; 2) Connection pool persistent (no TLS handshake ad ogni request); 3) Stripe SDK ha pooling integrato in maxRetries config; 4) Edge proxy (Cloudflare Workers, AWS Lambda@Edge) per route checkout in regione più vicina cliente. Monitor real user metrics (RUM): time-to-first-byte per checkout endpoint, p95 deve essere <500ms inclusi roundtrip Stripe.
Pricing rate limit e enterprise tier
Stripe rate limit pricing-aware: customer enterprise (alto volume, alto tier) ottengono rate limit più alti senza richiesta esplicita. Indicatori upgrade: 1) Volume mensile > 5M USD; 2) 5+ team member su Dashboard; 3) Integration multiple (Connect, Issuing, Billing); 4) Geography internazionale; 5) Custom contract negotiated. Per chi opera in scale, contattare Account Manager Stripe per: rate limit upgrade, pricing custom (lower fee con commitment volume), dedicated support, SLA contract. Per startup early stage, rate limit default sono ampi - focus su building product, scaling concerns vengono dopo product-market fit.
Procedura passo-passo
- Pianifica il throughput: stima quante chiamate/sec ti servono.
- Se vicino al limite, usa batch operations dove possibile (es. expand su list).
- Implementa rate limiter client-side (es. token bucket) per non superare 80% del limite.
- Gestisci 429: leggi Retry-After header e attendi prima di ritentare.
- Implementa exponential backoff con jitter per retry.
- Logga ogni 429 per monitorare quando avvicini il limite.
- Se hai bisogno di più throughput, contatta Stripe support per richiedere aumento.
- Usa webhook invece di polling per ridurre il carico API.
Errori comuni e come risolverli
- Polling aggressivo: consuma rate limit senza necessità; usa webhook.
- Retry senza backoff: amplifica il problema; backoff è obbligatorio.
- Concurrency non controllata: 10 worker che chiamano contemporaneamente saturano subito.
- Ignorare 429 e considerare succeeded: perdi operazioni; gestisci sempre il retry.
Domande frequenti
D: Posso aumentare i limiti?
R: Sì, contatta Stripe Support con i volumi richiesti e use case.
D: Le restricted key hanno limiti diversi?
R: Stessi limiti, ma scope ridotto.
D: Posso vedere quanto consumo?
R: Non c'è metric pubblico; monitora i 429 nei tuoi log.
D: Webhook hanno rate limit?
R: No, sono push verso di te; il tuo server deve sostenerli.
Hai bisogno di aiuto?
Se vuoi integrare Stripe con il team di G Tech Group, scrivici tramite il modulo di contatto.