Working with the API
Rate limits.
The budgets every call draws from, the headers that show what is left, and how to never be stopped by a 429.
On this page
Every call draws from a few budgets at once, and goes through only if all of them have room. Each budget refills steadily over the minute and allows a short burst on top, so a bot that sends at an even pace never meets a limit.
The budgets#
| Budget | Calls a minute | Burst | Counts |
|---|---|---|---|
| Your key, reading | 600 | 120 | Every call of the key that only reads |
| Your key, trading | 120 | 20 | Every call that needs trade access |
| One account | 180 | 30 | Every order placed, changed or canceled on that account, whichever key sends it |
| New orders on one account | 60 | 60 | Every order placed on that account through the API (a TradingView alert's too); and 5000 a day |
| Bulk calls | 6 | 3 | cancel-all and flatten, per key |
| What-if | 120 | 30 | POST .../orders/test |
| All your keys | 1800 | 300 | Every call of every key you hold |
| One address | 1200 | 300 | Every call with a key from one IP address |
| No key | 300 | 60 | Calls without a key (markets, status, limits), per address |
A key can be given lower numbers of its own in the dashboard, to keep one bot from using up what the others need. Your code can read every budget as it stands from GET /v1/limits.
From one address, 20 calls a minute with a key that does not work block that address for 15 minutes.
The streams, webhooks, TradingView alerts and AI assistants have budgets of their own: see Streams, Webhooks, TradingView and AI assistants.
The headers#
Every answer shows the tightest budget the call drew from, a refusal too (a read key on a trade call draws from its reading budget):
| Header | What it says |
|---|---|
X-RateLimit-Limit | That budget's calls a minute |
X-RateLimit-Remaining | The calls it has left right now |
X-RateLimit-Reset | Seconds until it is full again |
X-RateLimit-Scope | Which budget it is: key, customer or ip |
When a budget is empty#
The call is refused with 429 rate_limited, a Retry-After header in seconds, and the budget in details.scope (account for an account's own budget, account_orders and account_orders_day for its new orders, bulk for cancel-all and flatten). Nothing of the call was done, so it is safe to send again once Retry-After has passed.
{
"error": {
"type": "rate_limit",
"code": "rate_limited",
"message": "Too many requests: slow down.",
"request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
"retryable": true,
"doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#rate_limited",
"details": { "scope": "key" }
}
}To stay clear of it:
- Pace yourself from
X-RateLimit-Remaininginstead of waiting for a 429. The SDKs do this: with a budget used up, the next call waits for its reset instead of being refused. - Stream instead of polling. The account stream tells you every order, fill and position change as it happens, with no call at all.
- Ask once for many. A list answers up to 200 items a call, and
cancel-allorflattenreplace a loop of single calls.