Rate Limiting

The Frame API uses a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession might see error responses that show up as status code 429.

  • For APIs, Frame 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.

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.

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.

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

Load testing

It's common for users to prepare for a major sales event by load testing their systems, with the Frame API running in test mode as part of it. We generally discourage this practice because API limits are lower in test mode, so the load test is likely to hit limits that it wouldn't hit in production. Test mode is also not a perfect stand-in for live API calls, and that can be somewhat misleading. For example, creating a charge in live mode sends a request to a payment gateway and that request is mocked in test mode, resulting in significantly different latency profiles.

As an alternative, we recommend building integrations so that they have a configurable system for mocking out requests to the Frame API, which you can enable for load tests. For realistic results, they should simulate latency by sleeping for a time that you determine by sampling the durations of real live mode Frame API calls, as seen from the perspective of the integration.