Rate limits
How many requests each API key can make, and what to do when it makes too many.
Each API key can send requests up to these rates.
| Key | Sustained rate | Burst |
|---|---|---|
| Live | 20 requests a second | 40 |
| Test | 5 requests a second | 10 |
The burst is how many requests you can send at once before the sustained rate applies.
Endpoint limits
A few endpoints also have their own, lower limit. A request to one of them counts against both. Reading payments, balances and webhook endpoints has no limit of its own.
| Endpoint | Key | Sustained rate | Burst |
|---|---|---|---|
| Create a payment, reverse a payment | Live | 10 requests a second | 20 |
| Create a payment, reverse a payment | Test | 2 requests a second | 5 |
| Get an access token, revoke a token | Any | 5 requests a second | 10 |
When you get a 429
A request over the limit is refused with 429 and no body, and these headers:
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before you retry. |
X-Rate-Limited-Reason | Which limit refused the request: global-rate for your key's overall limit, endpoint-rate for an endpoint's own limit. |
Wait at least Retry-After seconds, then retry. If you retry in a loop, wait longer after each 429: for example 1
second, then 2, then 4. A refused request did nothing, so retry a payment with the same
idempotency key.
Staying under the limit
- Reuse an access token until it expires, instead of getting a new one for each call.
- Use webhooks instead of asking for a payment's status again and again.
- Spread batch work, such as payouts to many customers, over time instead of sending it all at once.