Learn about API rate limits and how to work with them
The SuperPath API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession may see error responses that show up as status code 429. We have several limiters in the API, including:
A rate limiter that limits the number of requests received by the API within any given second.
For most APIs, SuperPath allows up to 100 read operations per second and 100 write operations per second in live mode, and 25 operations per second for each in test mode.
A concurrency limiter that limits the number of requests that are active at any given time. Problems with this limiter are less common compared to the request rate limiter, but it’s more likely to result in resource-intensive, long-lived requests.
Treat these limits as maximums and don’t generate unnecessary load. See Handling limiting gracefully for advice on handling 429s. If you suddenly see a rising number of rate limited requests, please contact support (support@superpath.io)
We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To request an increased rate limit, please contact support. If you’re requesting a large increase, contact us 6 weeks in advance of when you’ll need the increased rate limit.
Rate limiting can occur under a variety of conditions, but it’s most common in these scenarios:
Running a large volume of closely-spaced requests can lead to rate limiting. Often this is part of an analytical or migration operation. When engaging in these activities, you should try to control the request rate on the client side (see Handling limiting gracefully).
Issuing many long-lived requests can trigger limiting. Requests vary in the amount of Stripe’s server resources they use, and more resource-intensive requests tend to take longer and run the risk of causing new requests to be shed by the concurrency limiter. Resource requirements vary widely, but list requests and requests that include expansions generally use more resources and take longer to run. We suggest profiling the duration of Stripe API requests and watching for timeouts to try and spot those that are unexpectedly slow.
A sudden increase in charge volume like a flash sale might result in rate limiting. We try to set our rates high enough that the vast majority of users are never rate limited for legitimate payment traffic, but if you suspect that an upcoming event might push you over the limits listed above, please contact support.
A basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We’d also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.
You can only optimize individual requests to a limited degree, so an even more sophisticated approach would be to control traffic to Stripe at a global level, and throttle it back if you detect substantial rate limiting. A common technique for controlling rate is to implement something like a token bucket rate limiting algorithm on the client-side. Ready-made and mature implementations for token bucket are available in almost any programming language.
A rate limiter that limits the number of requests received by the API within any given second.
For most APIs, SuperPath allows up to 100 read operations per second and 100 write operations per second in live mode, and 25 operations per second for each in test mode.
A concurrency limiter that limits the number of requests that are active at any given time. Problems with this limiter are less common compared to the request rate limiter, but it’s more likely to result in resource-intensive, long-lived requests.
Treat these limits as maximums and don’t generate unnecessary load. See Handling limiting gracefully for advice on handling 429s. If you suddenly see a rising number of rate limited requests, please contact support (support@superpath.io)
We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To request an increased rate limit, please contact support. If you’re requesting a large increase, contact us 6 weeks in advance of when you’ll need the increased rate limit.
Common causes and mitigations
Rate limiting can occur under a variety of conditions, but it’s most common in these scenarios:
Running a large volume of closely-spaced requests can lead to rate limiting. Often this is part of an analytical or migration operation. When engaging in these activities, you should try to control the request rate on the client side (see Handling limiting gracefully).
Issuing many long-lived requests can trigger limiting. Requests vary in the amount of Stripe’s server resources they use, and more resource-intensive requests tend to take longer and run the risk of causing new requests to be shed by the concurrency limiter. Resource requirements vary widely, but list requests and requests that include expansions generally use more resources and take longer to run. We suggest profiling the duration of Stripe API requests and watching for timeouts to try and spot those that are unexpectedly slow.
A sudden increase in charge volume like a flash sale might result in rate limiting. We try to set our rates high enough that the vast majority of users are never rate limited for legitimate payment traffic, but if you suspect that an upcoming event might push you over the limits listed above, please contact support.
Handling limiting gracefully
A basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We’d also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.
You can only optimize individual requests to a limited degree, so an even more sophisticated approach would be to control traffic to Stripe at a global level, and throttle it back if you detect substantial rate limiting. A common technique for controlling rate is to implement something like a token bucket rate limiting algorithm on the client-side. Ready-made and mature implementations for token bucket are available in almost any programming language.
Updated on: 13/02/2025
Thank you!