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

# 限制

> JoyToken 当前执行的额度、策略和钱包限制

JoyToken 当前公开限制主要来自 API Key 额度、Key 策略和钱包余额预检查。不要假设固定 QPS、RPM 或 TPM 配额。

## 当前限制

| 限制         | 来源                   | 命中结果                     |
| ---------- | -------------------- | ------------------------ |
| 每日额度       | API Key 预算           | `402 insufficient_quota` |
| 每周额度       | API Key 预算           | `402 insufficient_quota` |
| 钱包余额       | 个人或组织钱包              | `402 insufficient_quota` |
| 模型黑名单      | API Key 策略           | `403 policy_rejected`    |
| 档位白名单      | API Key 策略和请求 `tier` | `403 policy_rejected`    |
| IP 白名单/黑名单 | API Key 策略           | `403 policy_rejected`    |

## 钱包与路由

每个请求都必须传入 `model: "auto"`。所有档位共用一个钱包，不再存在按 tier 独立的余额；当策略、tier、钱包和预算过滤后没有可用候选时，请求会直接失败，而不会选择调用方指定的其他模型。

## 客户端处理

| 错误            | 是否重试 | 处理方式             |
| ------------- | ---- | ---------------- |
| `400`         | 否    | 修正请求体            |
| `401`         | 否    | 补充 API Key       |
| `402`         | 否    | 充值或调整 Key 预算     |
| `403`         | 否    | 调整策略、IP、tier 或模型 |
| `502`         | 可短退避 | 可能是路由或上游临时失败     |
| `503` / `504` | 是    | 指数退避重试           |

## 指数退避

```ts
const retryableStatuses = new Set([502, 503, 504]);

export async function withJoyTokenRetry<T>(fn: () => Promise<T>, attempts = 3) {
  let lastError: unknown;

  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await fn();
    } catch (error: any) {
      lastError = error;
      const status = error?.status ?? error?.response?.status;
      if (!retryableStatuses.has(status) || attempt === attempts - 1) throw error;
      await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** attempt));
    }
  }

  throw lastError;
}
```