# 限流 (/docs/api/rate-limits)



Praxis 的限流分两层：**平台层**按你的 Key 限每秒请求数和同时进行的请求数；**模型层**按模型限每分钟请求数（RPM）和每分钟 token 数（TPM）。每个响应——不论成功还是 `429`——都带三个 `x-ratelimit-*` 头，写明当前额度和重置时间，你不需要猜，也不需要为读额度多发请求。

## 两层限额 [#两层限额]

| 层   | 按什么计                | 限什么                               | 超出的表现                       |
| --- | ------------------- | --------------------------------- | --------------------------- |
| 平台层 | 你的 Key（没带凭证时按来源 IP） | 每秒请求数、同时进行的请求数                    | `429` + `retry-after`，等待后重试 |
| 模型层 | 模型 × 租户             | 每分钟请求数（RPM）、每分钟 token 数（TPM）、月度预算 | `429`，见下文模型层                |

两层的 `429` 都带同样的三个限流头；是哪一层触发的，看错误体的说明（[错误](/docs/api/errors)）。

## 平台层：每秒请求数与并发数 [#平台层每秒请求数与并发数]

默认每个 API Key **每秒最多 5 个请求，同时最多 4 个在途请求**。流式请求在流结束前占用并发槽位。超过任一默认限额返回 `429`，响应带 `ratelimit-limit`、`ratelimit-remaining`、`ratelimit-reset` 和 `retry-after`；并发超限须等已有请求结束。

实际限额可能因账户而异；以响应头和并发错误详情为准。

### 三个响应头 [#三个响应头]

```http
x-ratelimit-limit-requests: 5
x-ratelimit-remaining-requests: 4
x-ratelimit-reset-requests: 850ms
```

| 头                                | 含义                                    |
| -------------------------------- | ------------------------------------- |
| `x-ratelimit-limit-requests`     | 该凭证每秒的请求上限                            |
| `x-ratelimit-remaining-requests` | 本秒还剩多少个请求                             |
| `x-ratelimit-reset-requests`     | 距离额度重置的时间：不满一秒写作 `850ms`，一秒及以上写作 `1s` |

同样的三个数也以 IETF 标准名 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`（整数秒）同时给出。以上 5 次/秒、4 个并发为默认限额；配置覆盖后的请求速率以响应头显示为准。

### 超出每秒上限 [#超出每秒上限]

一秒内的第 N+1 个请求（N 为该 Key 的每秒上限）返回 `429`，并带 `retry-after`（整数秒，通常是 `1`）。**被拒绝的请求不消耗额度**：`x-ratelimit-remaining-requests` 保持 `0`，等窗口重置即可恢复。

### 超出并发上限 [#超出并发上限]

同时进行的请求（包括尚未结束的流式响应——流结束前一直占坑）超过该 Key 的并发上限时，多出的请求返回 `429`，`retry-after` 为 `1`。这种情况下**仅等待秒级窗口重置不会释放并发槽位**：须等一个进行中的请求结束。是并发还是每秒触发的，错误说明里写得很清楚（"Concurrent request limit …" / "Requests per second limit …"）。

### 错误体 [#错误体]

错误体跟着地址第一段走（见[错误](/docs/api/errors)）。`/model/v1/chat/completions` 等原生端点是 Problem Details：

```json
{
  "type": "https://deepraxis.ai/problems/rate_limit",
  "title": "rate_limited",
  "status": 429,
  "detail": "Requests per second limit of 5 exceeded for this credential. Retry after the listed wait.",
  "instance": "problem_eqfnxu",
  "kind": "rate_limit",
  "scope": "platform",
  "retryable": true
}
```

`scope: "platform"` 表示是平台层触发的（模型层限额的错误不带此字段或为 `model`）。`/openai/v1/chat/completions` 等厂商前缀按该家的错误格式，例如 OpenAI 兼容端点：

```json
{ "error": { "code": 429, "type": "rate_limit_error", "message": "Requests per second limit of 5 exceeded for this credential. Retry after the listed wait." } }
```

### 没带凭证的请求 [#没带凭证的请求]

公开端点（如 `GET /model/v1/models`）允许不带 Key 调用，这时按**来源 IP** 计入一个较小的匿名额度，响应头同样给出。带了 Key 就按 Key 计，与 IP 无关。

`GET /meta/v1/health` 不限流，探活监控可以任意频率调用。

## 模型层：每分钟请求数与 token 数 [#模型层每分钟请求数与-token-数]

限额维度是**模型 × 租户 × 分钟**，不是 API Key：

* 每个模型在模型元数据里配置自己的 **RPM**（每分钟请求数）与 **TPM**（每分钟 token 数）；未配置或为 `0` 表示不限制。
* 命中任一限额返回 `429`，`type` 为 `rate_limit_error`，`Retry-After: 60`，`problem.details.rateLimit` 给出当前值与限额。
* **BYOK 调用自带供应商凭证，不占平台模型限额。**
* 上游供应商限流由平台自动 failover 到其他供应商；全部供应商不可用时按返回的 `429` 处理。

模型另有**月度预算**：按模型当月累计收入计，超出返回 `429`，`type` 为 `budget_error`（`QUOTA_EXHAUSTED`），无 `Retry-After`——等待无效，需要提升该模型的预算。

错误体与状态码见[错误](/docs/api/errors)；账号额度见[配额与限流](/docs/cloud/account/quotas)。