Stripe hits you with a 429 status code at 2 a.m. on a Sunday. Your payment queue backs up. Customers can’t check out. Your on-call engineer has no idea what happened because there’s no retry logic in place.
This happens more often than you’d think. Most engineers treat Stripe rate limiting as a “won’t happen to us” problem until it does. By then, you’ve lost transactions, frustrated users, and burned through incident response time that could have been spent shipping.
Stripe rate limiting isn’t a bug in your code—it’s a feature of Stripe’s infrastructure that you need to architect around. This post covers how to handle it right: exponential backoff, circuit breakers, idempotency keys, and the monitoring that actually matters.
What Stripe Rate Limiting Is (And Why It Matters)
Stripe enforces rate limits to protect their infrastructure from being hammered by a single account. The limits vary by account age, volume, and tier, but the practical ceiling for most accounts is somewhere between 100 and 300 requests per second. That sounds high until you realize a single checkout flow can touch Stripe 5–10 times: create customer, create payment intent, retrieve invoice, create subscription, update metadata, retrieve balance, etc.
When you hit the limit, Stripe returns HTTP 429 with a Retry-After header telling you how many seconds to wait. Most developers ignore this header or don’t implement retry logic at all. They ship the error to the user instead. This is why you see checkout failures that resolve themselves if you refresh the page.
The real cost isn’t the momentary failure—it’s the cascading effect. If your payment processing is blocking your user experience, rate limits turn into lost revenue. If you’re running a background job that processes invoices and hits a rate limit, the entire job fails and you’re manually re-running it at 6 a.m. If you’re a SaaS platform making Stripe calls on behalf of your customers, one customer’s spike in activity can rate-limit calls for everyone.
Stripe publishes their rate limits in their documentation, but they’re deliberately vague about the exact thresholds. The reason: they don’t want you gaming the system. What they do tell you is that rate limits are account-specific, not global. A customer hitting limits doesn’t affect another customer. But within your own account, you need to assume you’ll hit 429s and handle them gracefully.
Recognizing Rate Limit Responses
Stripe’s rate limit response is straightforward, but easy to miss if you’re not looking for it. When rate-limited, you get a 429 status code with a JSON body like this:
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests in a short period",
"type": "invalid_request_error"
}
}The HTTP headers include Retry-After: 2, telling you to wait 2 seconds before retrying. If you’re using the official Stripe Node.js library, it handles some of this for you—but only if you configure it correctly. The default behavior is to throw an error and let your code decide what to do.
Most Stripe errors are not retryable. A 400 Bad Request (invalid card, expired token, etc.) will fail the same way every time. A 500 Server Error from Stripe is rare but transient. A 429 is the exception: it means “try again later.” Conflating these is a common mistake. Your retry logic should only apply to 429s and specific 5xx errors (timeouts, 503 Service Unavailable). Everything else should fail fast.
If you’re making direct HTTP calls to Stripe’s API instead of using their SDK, you need to parse the Retry-After header yourself. It’s the source of truth for how long to wait. Ignore it and you’ll just hit the rate limit again immediately.
Exponential Backoff with Jitter
The naive approach to rate limiting is to sleep and retry: hit a 429, wait 2 seconds, try again. If you’re retrying from multiple processes or servers, they’ll all wake up at the same time and hammer Stripe in unison, creating a thundering herd. This makes the rate limit worse, not better.
The solution is exponential backoff with jitter. You wait progressively longer between retries, and you randomize the wait time slightly so that parallel retries don’t all hit Stripe at the same instant.
Here’s a real implementation in Node.js:
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
async function callStripeWithBackoff(fn, maxRetries = 5) {
let attempt = 0;
let lastError;
while (attempt < maxRetries) {
try {
return await fn();
} catch (error) {
// Only retry on 429 or specific transient errors
if (error.statusCode !== 429 && error.statusCode !== 503) {
throw error; // Fail fast on non-retryable errors
}
lastError = error;
attempt++;
if (attempt >= maxRetries) {
break;
}
// Exponential backoff: 1s, 2s, 4s, 8s, 16s
const baseWait = Math.pow(2, attempt);
// Add jitter: random value between 0 and baseWait
const jitter = Math.random() * baseWait;
const waitMs = (baseWait + jitter) * 1000;
console.log(`Rate limited. Attempt ${attempt}/${maxRetries}. Waiting ${Math.round(waitMs / 1000)}s.`);
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
throw lastError; // All retries exhausted
}
// Usage
await callStripeWithBackoff(async () => {
return await stripe.charges.create({
amount: 2000,
currency: 'usd',
source: 'tok_visa',
});
});This implementation respects Stripe’s Retry-After header implicitly (you could parse it explicitly if you want tighter control). The jitter is critical—it’s what keeps multiple retrying clients from synchronizing. Without it, you get thundering herd behavior where all your servers retry at exactly the same moment, making the congestion worse.
One caveat: this approach blocks your thread or process while waiting. In a high-concurrency Node.js application, this can starve other requests. For better isolation, move rate-limited calls into a background queue with its own retry logic, separate from your request path. That way, a Stripe rate limit doesn’t block your user-facing API.
The Circuit Breaker Pattern
Exponential backoff handles individual rate-limited requests, but it doesn’t protect against systemic problems. If Stripe is consistently rate-limiting your account, retrying harder just wastes time and delays user-facing errors longer.
The circuit breaker pattern solves this. Think of it like an electrical circuit breaker: when too many failures happen in a time window, the circuit “opens” and stops sending requests for a period, returning fast failures instead. Once the window passes, it “half-opens” and allows a test request through. If that succeeds, the circuit closes and normal operation resumes.
For Stripe specifically, a circuit breaker is useful when you’re getting rate-limited consistently—not just once, but repeatedly. It tells you “we’re hitting Stripe’s limits right now; stop trying until things calm down.” This prevents your application from burning through retry budgets and delaying errors to users.
Here’s a practical implementation using a simple in-memory state machine:
class StripeCircuitBreaker {
constructor(options = {}) {
this.failureThreshold = options.failureThreshold || 5; // Open after 5 failures
this.successThreshold = options.successThreshold || 2; // Close after 2 successes
this.timeout = options.timeout || 30000; // Half-open state lasts 30s
this.windowSize = options.windowSize || 60000; // Track failures in 60s window
this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
this.failures = [];
this.successCount = 0;
this.nextAttemptTime = null;
}
async execute(fn) {
// Clean old failures outside the window
const now = Date.now();
this.failures = this.failures.filter(time => now - time < this.windowSize);
if (this.state === 'OPEN') {
if (now < this.nextAttemptTime) {
throw new Error('Circuit breaker is OPEN. Stripe is rate-limited.');
}
// Timeout expired, transition to HALF_OPEN
this.state = 'HALF_OPEN';
this.successCount = 0;
}
try {
const result = await fn();
this.onSuccess();
return result;
} catch (error) {
this.onFailure(error);
throw error;
}
}
onSuccess() {
this.failures = []; // Reset failures on success
if (this.state === 'HALF_OPEN') {
this.successCount++;
if (this.successCount >= this.successThreshold) {
this.state = 'CLOSED';
console.log('Circuit breaker CLOSED. Stripe is responding normally.');
}
}
}
onFailure(error) {
// Only count rate limit errors
if (error.statusCode === 429) {
this.failures.push(Date.now());
if (this.failures.length >= this.failureThreshold) {
this.state = 'OPEN';
this.nextAttemptTime = Date.now() + this.timeout;
console.log(`Circuit breaker OPEN. Stripe rate-limited ${this.failures.length} times. Waiting ${this.timeout}ms.`);
}
}
}
}
// Usage
const breaker = new StripeCircuitBreaker();
await breaker.execute(async () => {
return await stripe.charges.create({ /* ... */ });
});This circuit breaker is stateful and local to your process. If you’re running multiple processes or servers, each maintains its own state. For distributed systems, you’d want a shared circuit breaker backed by Redis, but for most applications, local state is sufficient and faster.
The key insight: a circuit breaker doesn’t prevent rate limits. It acknowledges them and fails fast instead of wasting resources on doomed retries. Combine it with exponential backoff: exponential backoff handles transient spikes, the circuit breaker handles sustained rate limiting.
Idempotency Keys and Safe Retries
Here’s a subtle problem: if you retry a Stripe request, you might create duplicate charges, invoices, or subscriptions. Stripe doesn’t know your retry is a retry—it looks like a new request.
The solution is idempotency keys. When you make a Stripe API call, you include an Idempotency-Key header with a unique identifier. If the request succeeds, Stripe stores the result. If you retry with the same key, Stripe returns the cached result instead of processing the request again. No duplicate charge. No duplicate invoice.
This is so important for payment processing that I’ve written about it separately—see Idempotency Keys: The Silent Killer of Payment Processing for a deep dive. But the short version: always use idempotency keys with Stripe.
const crypto = require('crypto');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY, {
maxNetworkRetries: 0, // We handle retries ourselves
});
async function createChargeWithIdempotency(chargeData) {
// Generate a deterministic idempotency key
// Use customer ID + timestamp + amount to create uniqueness
const idempotencyKey = crypto
.createHash('sha256')
.update(`${chargeData.customerId}-${chargeData.createdAt}-${chargeData.amount}`)
.digest('hex');
try {
return await stripe.charges.create(chargeData, {
idempotencyKey,
});
} catch (error) {
if (error.statusCode === 429) {
// Safe to retry—idempotency key protects against duplicates
console.log(`Rate limited. Retrying with idempotency key: ${idempotencyKey}`);
// Implement exponential backoff here
await new Promise(resolve => setTimeout(resolve, 2000));
return await stripe.charges.create(chargeData, {
idempotencyKey,
});
}
throw error;
}
}Without idempotency keys, you’re forced to choose between two bad options: don’t retry (lose transactions), or retry and risk duplicates. With idempotency keys, retries are safe. This is why it’s a foundational pattern for reliable payment processing.
Monitoring and Alerting
The last piece is visibility. If you’re hitting rate limits, you need to know about it—not from users complaining, but from metrics and alerts.
Track these signals:
- 429 response count per minute—When this spikes, you’re hitting Stripe’s limits. Alert if it’s sustained for more than a few minutes.
- Retry attempts per request—If your average request is being retried 3+ times, Stripe is struggling to keep up with your traffic. This might mean you need to batch requests or optimize your call patterns.
- Circuit breaker state changes—Log every time the circuit breaker opens or closes. This gives you a clear signal of when Stripe rate limiting is affecting you.
- Stripe API latency—Rate-limited requests take longer (because of backoff). High latency can indicate you’re approaching or hitting limits.
Here’s a minimal Prometheus instrumentation:
const client = require('prom-client');
const stripeRateLimitCounter = new client.Counter({
name: 'stripe_rate_limit_errors_total',
help: 'Total number of Stripe 429 rate limit errors',
});
const stripeRetryCounter = new client.Counter({
name: 'stripe_retries_total',
help: 'Total number of Stripe request retries',
});
const stripeLatencyHistogram = new client.Histogram({
name: 'stripe_request_duration_seconds',
help: 'Stripe API request latency',
buckets: [0.1, 0.5, 1, 2, 5],
});
async function instrumentedStripeCall(fn) {
const timer = stripeLatencyHistogram.startTimer();
let retries = 0;
try {
while (retries < 5) {
try {
const result = await fn();
return result;
} catch (error) {
if (error.statusCode === 429) {
stripeRateLimitCounter.inc();
retries++;
stripeRetryCounter.inc();
// exponential backoff here
await new Promise(resolve => setTimeout(resolve, Math.pow(2, retries) * 1000));
} else {
throw error;
}
}
}
} finally {
timer();
}
}Once you have these metrics, set up alerts in your monitoring system (Grafana, Datadog, etc.). A useful threshold: alert if you see more than 5 rate limit errors in a 5-minute window. This tells you something is off before it becomes a customer-facing problem.
Beyond metrics, look at your Stripe usage patterns. Are you making redundant API calls? Could you batch operations? For example, creating 100 charges individually hits Stripe 100 times. Using Stripe’s batch processing API (if available) or grouping operations reduces calls. Less traffic means less chance of hitting limits.
A production system handling payments should never surprise you with a rate limit. The combination of exponential backoff, circuit breakers, idempotency keys, and monitoring means you’re not just handling rate limits reactively—you’re architecting around them proactively. Rate limits become a known, managed constraint instead of a silent failure.
If you’re building a SaaS platform or payment-heavy system where Stripe reliability is critical, this is the kind of detail that separates a system that works most of the time from one that works reliably. We help teams architect payment systems that ship reliably at scale—apply for an engagement if you’re solving this problem and want senior engineering judgment on your design.
