> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytespike.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 速率限制与并发

> Per-key 速率限制桶（5h / 1d / 7d）、并发上限、要读哪些响应头，以及触上限时 429 长什么样。

ByteSpike **按 API key** 强制三条滚动窗口的花费上限，加一条并发上限。这四条彼此独立 —— 最紧的那条说了算。

## 四条上限

| 上限                               | 默认   | 在哪设                                                               |
| -------------------------------- | ---- | ----------------------------------------------------------------- |
| `rate_limit_5h`（滚动 5 小时 USD 花费）  | 不限   | 按 key，在 [Console → API keys](https://console.bytespike.ai/keys) 里 |
| `rate_limit_1d`（滚动 24 小时 USD 花费） | 不限   | 按 key                                                             |
| `rate_limit_7d`（滚动 7 天 USD 花费）   | 不限   | 按 key                                                             |
| 并发（in-flight 请求数）                | 按档定义 | 按订阅档；见 [价格](/zh/pricing)                                          |

任一花费上限填 `0` = 不限。

## 它们如何相互作用

每个请求网关计算：

```
remaining_5h  = rate_limit_5h - 过去 5h 花费
remaining_1d  = rate_limit_1d - 过去 1d 花费
remaining_7d  = rate_limit_7d - 过去 7d 花费
```

响应携带三者中 **最紧** 的：

```
X-RateLimit-Limit: 50.00            # 最接近限制你的那条桶的上限
X-RateLimit-Remaining: 4.18         # 该桶剩余
X-RateLimit-Reset: 1716705600       # 该桶重置的 Unix ts
```

当 `Remaining` 归零，下一次请求返回 `429`：

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "message": "rate_limit_5h exceeded: 50.00 / 50.00 used; resets at 2026-05-25 14:00:00 UTC"
  }
}
```

（`/v1/messages` 用 Anthropic 形状；`/chat/completions` + `/responses` 用 OpenAI 形状。）

## 怎么取值

| 用法                    | 推荐上限                                                                    |
| --------------------- | ----------------------------------------------------------------------- |
| Dev / 本地笔记本           | `rate_limit_5h = 5`、`_1d = 20`、`_7d = 50` —— 不挡正常工作，又能挡住后台跑飞的死循环        |
| 生产 API key            | `_5h = 100`、`_1d = 500`、`_7d = 2000` —— 大约期望用量的 10×。能吸收流量峰值，又能兜住跑飞的 bug |
| Per-customer key（多租户） | 三条都设成该客户的额度 —— 一客户一 key，附上他们计费周期的上限                                     |
| 长跑批任务                 | `_5h` 拉高（让批跑），`_1d` 和 `_7d` 较低（防止跑飞循环几天）                                |

`quota`（终身上限）和 `expires_in_days` 与速率限制桶分开 —— 互不影响。见 [鉴权](/zh/authentication#per-key-controls)。

## 并发

并发是你账号下任意时刻 in-flight 的请求数（跨所有 key）。按订阅档设：

| 档位         | 并发上限            |
| ---------- | --------------- |
| Free       | 5               |
| Pro        | 25              |
| Max        | 100             |
| Enterprise | 自定（通常 500–2000） |

触上限时，新请求立即返回 `429`，附 `type: "rate_limit_error", code: "concurrency_limit"`。推荐响应跟常规 `429` 一样 —— 退避 + 重试。

如果你在 Free / Pro 上撞到并发墙、花费上限还远，升级档位而不是多开 key。这条上限是账号级，不是 key 级。

## 退避策略

网关给的重置时间戳是精确的 —— 用它，而不是用指数退避去猜：

```python theme={null}
import time, requests

def call_with_backoff(payload):
    while True:
        r = requests.post(URL, json=payload, headers=HEADERS)
        if r.status_code != 429:
            return r
        reset = int(r.headers.get("X-RateLimit-Reset", 0))
        wait = max(1, reset - int(time.time()))
        time.sleep(min(wait, 300))   # 封顶 5 分钟，免得卡住的 reset 把我们死锁
```

对并发 429（没有 `X-RateLimit-Reset`），用短的抖动退避（例如 `1 + random()*2` 秒）—— 上限随 in-flight 请求完成而清，可能不到一秒。

## *不* 受速率限制

* `GET /api/v1/me/*` 管理类调用 —— 免费，从不限流
* `GET /api/v1/me/usage` —— 免费
* `GET /api/v1/me/account` —— 免费
* `POST /v1/tasks/query` —— 免费，不计入并发
* `POST /v1/tasks/cancel` —— 免费，不计入并发
* Console 的 dial-test —— 用 cookie 鉴权，不是 key，从不扣费

任何对 `/v1/messages`、`/v1/chat/completions`、`/v1/responses`、`/v1beta/...`、`/v1/images/*`、`/v1/tasks/submit` 的请求都计入。

## 读 usage 日志

要 debug 429 —— 看哪儿在花钱：

```bash theme={null}
curl 'https://llm.bytespike.ai/api/v1/me/usage?limit=100&api_key_id=42' \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY"
```

把对应窗口里的 `credits` 加起来。响应头里最紧的那条桶告诉你看哪个窗口。

## 抬上限

| 你想要             | 操作                                                                         |
| --------------- | -------------------------------------------------------------------------- |
| 抬高 per-key 花费上限 | 在 [Console → API keys](https://console.bytespike.ai/keys) 编辑 key           |
| 抬高账号并发          | 在 [Console → Subscriptions](https://console.bytespike.ai/subscriptions) 升档 |
| Max 档之外的自定义上限   | 邮件给 [enterprise@bytespike.ai](mailto:enterprise@bytespike.ai)              |

## 相关

* [鉴权](/zh/authentication) —— 完整的 per-key 控制清单
* [Credits 与账单](/zh/concepts/credits-and-billing) —— 花费如何累计
* [错误处理](/zh/concepts/error-handling) —— 错误信封 + 重试语义