Concurrency limits
There is no rate limit. There is a cap on how many requests you can have open at once.
This catches people out, because almost every other API you integrate with counts requests per second. We count requests in flight.
How it works
Your account carries a cap per mode. While you have that many requests open,
the next one is refused immediately with 429 rather than queued.
| Default when nothing is set | |
|---|---|
| Live | 20 in flight |
| Test | 5 in flight |
max_concurrent_requests on Get account reports
what is recorded on your account. If it reads 0, nothing was set for you and
the default above applies.
Live and test are counted separately, so sandbox testing cannot crowd out production.
Placing an order gets priority
Not every route may use the whole cap. Placing an order may; everything else is held below it, so that polling and catalogue reads can never use up the slots your next sale needs.
The reserved share is a quarter of the cap, at least one:
| Your cap | Orders may use | Everything else may use |
|---|---|---|
| 20 (live default) | 20 | 15 |
| 5 (test default) | 5 | 4 |
| 8 | 8 | 6 |
So with the live default you can have 15 polls and reads open and still place an order. The reverse is not true: 20 orders in flight will refuse your next poll, which is the trade-off chosen deliberately.
When you hit it
{
"success": false,
"status": "failed",
"code": 429,
"message": "Too many requests in flight. Wait for your open requests to finish before sending more.",
"data": null
}Retry-After is always 1.
Important
Do not respond to this with a fixed back-off. The limit is not time-based, so
waiting 30 seconds achieves nothing a shorter wait would not, and waiting is
not really the fix. The fix is to cap your own concurrency: a worker pool, or
a semaphore, sized a little under your cap. Then you never see a 429 at all.
A refused request is not logged in your API call log, and is not counted as a
call. It also never reached a handler, so nothing was charged and no order was
created. A 429 on POST /reseller/orders means that order does not exist and
is safe to send again.
Sizing your own side
Start with a pool of about three quarters of your cap and leave headroom. If you genuinely need more, ask us: the cap is a number on your account, not a property of the API.
What is not limited
- Requests per second, minute or day. No such limit exists.
- Total orders. Your balance is the only ceiling.
- Payload size, beyond a 64 KiB body, which no legitimate request approaches.
Timeouts
Give a verify or an order a generous client timeout. Meter verification talks to a distribution company and is the slowest call in the API; a two-second timeout will cut off calls that were about to succeed, and for orders that leaves you not knowing whether one was placed.
Thirty seconds is a sensible floor for verify and order. Reads can be tighter. And whatever you choose, treat a timeout as "unknown" rather than "failed": the reference, and retrying safely covers how.