# Rate limits

The budgets every call draws from, the headers that show what is left, and how to never be stopped by a 429.

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](/guides/streams), [Webhooks](/guides/webhooks), [TradingView](/guides/tradingview) and [AI assistants](/mcp).

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

```json
{
  "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-Remaining` instead 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](/guides/streams) 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-all` or `flatten` replace a loop of single calls.
