> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# 策略保护

> 用 API Key 策略控制来源、路由、tier 和预算

策略保护用于限制一把 API Key 能从哪里调用、能使用哪些 tier、自动路由可命中哪些模型，以及最多消耗多少额度。

## 推荐配置

| 场景             | 建议                    |
| -------------- | --------------------- |
| 本地开发           | 单独 Key，较小预算，先用 `auto` |
| 开发后端           | IP 白名单、明确 tier、预算限制   |
| 编码 Agent / IDE | 独立 Key，较小每日或每周额度      |
| 高风险 Agent      | Key 预算 + 应用侧停止条件      |
| 稳定开发链路         | 固定 tier 和 Key 预算      |

## 可配置限制

| 限制                    | 作用                                        |
| --------------------- | ----------------------------------------- |
| IP 白名单 / 黑名单          | 限制请求来源                                    |
| allowed tiers         | 限制可使用的 `economy` / `standard` / `premium` |
| model blacklist       | 从自动路由候选中排除模型                              |
| daily / weekly budget | 限制周期额度                                    |
| routing strategy      | 控制自动路由偏好                                  |

## 请求被拒绝时

| 错误                       | 常见原因                         |
| ------------------------ | ---------------------------- |
| `403 invalid_api_key`    | Key 无效、撤销、过期或不是 active       |
| `403 policy_rejected`    | IP、tier、模型黑名单或 blocked 策略不满足 |
| `402 insufficient_quota` | 钱包余额不足、预算不足或预冻结失败            |

## 变更策略

推荐用新 Key 替换旧 Key：

1. 创建新 Key，并绑定新策略。
2. 在测试环境发一条带 `X-Request-ID` 的请求。
3. 在 JoyToken Console 确认日志和用量正常。
4. 切换测试环境变量。
5. 观察一段时间后 revoke 旧 Key。