# 限流
> 两级固定窗口限流、X-RateLimit 响应头与 429 处理。

REST API（`/v1`）请求按两级固定窗口计数限流，**任一超限即 429**：

| 级别 | 额度 | 窗口 |
| --- | --- | --- |
| 账户级 | 600 次/分钟 | 60s |
| API key 级 | 120 次/分钟 | 60s |

以上额度是平台统一设置：所有账户、所有 API key 的额度相同，不按账户单独配置。

## 响应头

以下响应头只在 `429`（`rate_limited`）响应上返回，成功响应不携带：

| Header | 说明 |
| --- | --- |
| `Retry-After` | 重试前需要等待的秒数 |
| `X-RateLimit-Limit-Tenant` / `X-RateLimit-Remaining-Tenant` | 账户级额度 / 剩余 |
| `X-RateLimit-Limit-Key` / `X-RateLimit-Remaining-Key` | key 级额度 / 剩余 |
| `X-RateLimit-Reset` | 距额度重置的秒数 |

## 429 处理

```json
{
  "error": {
    "code": "rate_limited",
    "type": "rate_limit_error",
    "message": "Tenant rate limit exceeded",
    "retryable": true,
    "details": {
      "scope": "tenant",
      "limit": 600,
      "window_seconds": 60,
      "retry_after_seconds": 12
    },
    "request_id": "req_..."
  }
}
```

`details.scope` 指明超限的级别（`tenant` 或 `api_key`），`details.limit` 是该级别的额度；`details.retry_after_seconds` 与 `Retry-After` 响应头一致。`tenant` 表示整个账户，`api_key` 表示这一把钥匙。

- 遵守 429 响应的 `Retry-After` 头（秒），再携带**相同的** `Idempotency-Key` 重试；
- 突发并发是触发限流最常见的原因，客户端做好请求平滑；
- 需要提额：控制台联系我们或找对接的账户经理。