Rate limits#
Rate limits keep the API fast and fair for everyone. They are generous for normal integrations: a checkout that creates a transaction, shows the account details and waits for a webhook never comes close.
Limits at a glance#
| Limit | Scope | Value |
|---|---|---|
| API requests | Per secret key | Bursts of up to 100 requests, refilling at 25 requests per second |
| Polling a transaction | GET /v1/transactions/{id}, per key and transaction | 1 request per second (a burst of 2 is tolerated); 5 seconds recommended |
| Realtime connections | Per merchant | Up to 500 concurrent socket connections |
Test and live keys have separate buckets, so heavy sandbox testing never slows down live traffic.
How the request limit works#
Each secret key has a token bucket that holds 100 tokens. Every request spends one token, and the bucket refills at 25 tokens per second. You can send a burst of 100 requests at once, then sustain 25 requests per second indefinitely.
Every authenticated response tells you where you stand:
| Header | Description |
|---|---|
X-RateLimit-Limit | Size of the bucket: 100. |
X-RateLimit-Remaining | Tokens left right now. |
Retry-After | On 429 responses only: seconds to wait before the next attempt. |
When the bucket is empty, the API responds with 429 Too Many Requests:
Polling limit#
GET /v1/transactions/{id} has its own, stricter limit: about one request per second for each transaction. If you
poll faster, you get a 429 with a specific message:
The response carries Retry-After: 1. Poll every 5 seconds, stop as soon as the status leaves pending, and
prefer the push channels below. See Polling for a complete loop.
Realtime limits#
The realtime socket at /v1/realtime does not count against the request limit, but it has its own rules:
- The server pings every 25 seconds. Sockets that stay silent for 60 seconds are dropped; Socket.IO clients answer pings automatically.
- A merchant can hold up to 500 concurrent connections. Close sockets when the customer leaves the checkout page.
- After a reconnect, subscribe again. The subscribe acknowledgement includes the transaction's current state, so nothing is missed.
Handling 429 responses#
Retry after the number of seconds in Retry-After. When there is no Retry-After (for example on a network error
or a 5xx), back off exponentially with jitter: 0.5 s, 1 s, 2 s, 4 s and so on, capped at a few seconds, with a
random spread so many workers do not retry in lockstep. Give up after a handful of attempts and surface the error.
The SDKs implement this for you. The examples show the settings and what to do when retries run out.
Staying well under the limits#
- Create one transaction per checkout and reuse it while it is
pending, instead of creating a new one on every page load. A reusedreferencereturns the existing transaction in the409 duplicate_referenceerror. - Cache data that rarely changes, such as the bank list.
- Spread batch jobs, such as nightly reconciliation that lists transactions, over time and page with
starting_afterandlimit(up to 100 items per page). - Watch
X-RateLimit-Remainingand slow down before it reaches zero.
If your expected volume needs higher limits, contact support with your use case.