限流与配额 — Markdown 源文

以下为可直接复制或提供给 AI Agent 的 Markdown 原文。
> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 限流与配额

SupaNexus 可能应用多层独立限制。具体阈值取决于你的部署环境 — 请咨询平台管理员或查看开发者控制台。

## 1. IP 限流

作用于 **所有路由**（含未携带有效 API Key 的请求），按客户端 IP 计量。

常见默认值：约 **120 次/分钟/IP**（启用时）。

超限时：

- **HTTP 429**
- OpenRouter 格式（`/v1/*` 与其它路由一致）：

```json
{
  "error": {
    "code": 429,
    "message": "You are being rate limited."
  }
}
```

响应可能包含 **`Retry-After`** 头（秒）。

> **说明：** 该限制按 **IP 地址** 计算，非按 API Key。

## 2. 用量配额（可选）

若为你的组织或项目配置了配额，可能仅对 `POST /v1/chat/completions` 生效。

超限时：

- **HTTP 429**
- `error.code`: **429**（数字）
- 可能设置 **`Retry-After`** 头（秒）

## 3. 账户余额（可选）

若启用了预付费或余额检查，可能仅对 `POST /v1/chat/completions` 生效。

| HTTP | 含义 |
|------|------|
| 402 | 本账期额度不足（`error.code=402`） |
| 403 | 缺少组织上下文 |

**402 vs 429：** 余额不足返回 **402 Payment Required**；配额或花费上限返回 **429 Too Many Requests**。

## 对比表

| 层级 | 典型范围 | 错误格式 | HTTP |
|------|----------|----------|------|
| IP 限流 | 全路由 | OpenRouter `{error:{code,message}}` | 429 |
| 用量配额 | 仅 Chat | OpenRouter | 429 |
| 账户余额 | 仅 Chat | OpenRouter | 402 |

## 最佳实践

- 对 429 做指数退避，遵守 `Retry-After`。
- 不同应用使用不同 API Key，便于在控制台区分用量。
- 在开发者控制台监控用量，避免触顶。

## 相关

- [错误处理](./errors.md)
- [Chat Completions](./chat-completions.md)