API 指南

限制

当前工程中已经落地的限制机制不是传统固定 QPS 限流，而是 API Key 额度、策略约束和钱包余额预检查。客户端文档需要按这些真实行为来写。

如果后续 gateway 增加每分钟请求数、并发数或 token-per-minute 限制，再把它补进本页。目前不要承诺固定 QPS、RPM 或 TPM 配额。

当前执行的限制

限制来源命中行为
每日额度API Key 校验返回的 limit_daily + Finance usage counter返回 402 insufficient_quota
每周额度API Key 校验返回的 limit_weekly + Finance usage counter返回 402 insufficient_quota
钱包余额wallet-service / finance client当前 tier 余额不足时返回 402 insufficient_quota，auto 模式下可能尝试换 tier
固定模型API Key 绑定的 fixed_model请求其他具体模型会返回 403 policy_rejected
模型黑名单策略快照命中后返回 403 policy_rejected
Tier 白名单策略快照 / API Key tier / 请求 tier不允许的 tier 会返回 403 policy_rejected
IP 白名单/黑名单策略快照不允许的来源 IP 会返回 403 policy_rejected

钱包回退

当请求使用 model: "auto" 或省略 model 时，JoyToken 可以在余额不足时尝试换 tier 重新路由。当前候选顺序是：

当前 tier回退顺序
premiumstandard -> economy
standardpremium -> economy
economystandard -> premium

如果请求指定了具体模型，网关不会为了余额不足自动改成其他模型。

客户端处理建议

错误是否重试建议
400 invalid_request_error否修正请求体、messages 或 body 大小
401 missing_api_key否补充 Bearer API Key
403 invalid_api_key否检查 API Key 是否有效且状态为 ACTIVE
403 policy_rejected否调整策略、IP、tier 或模型
402 insufficient_quota否充值、切换账单账户、调整 Key 额度或降低 tier
502 routing_error可短退避可能是路由服务或候选模型问题
502 upstream_error可短退避可能是提供方临时失败
503 / 504是使用指数退避，并保留请求日志

指数退避示例

retry.ts
1const retryableStatuses = new Set([502, 503, 504]);
2
3export async function withJoyTokenRetry<T>(fn: () => Promise<T>, attempts = 3) {
4  let lastError: unknown;
5
6  for (let attempt = 0; attempt < attempts; attempt += 1) {
7    try {
8      return await fn();
9    } catch (error: any) {
10      lastError = error;
11      const status = error?.status ?? error?.response?.status;
12      if (!retryableStatuses.has(status) || attempt === attempts - 1) {
13        throw error;
14      }
15      await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** attempt));
16    }
17  }
18
19  throw lastError;
20}

对 402 和 403 做无限重试通常只会放大流量，应该先修正账户、策略或请求配置。