TokenFlow

错误码

出错时返回的不是 HTML 页面,是下面这种 JSON。判断依据优先看 HTTP 状态码, type 字段用来区分同一状态码下的不同原因。

返回体结构

错误响应
{
  "error": {
    "message": "令牌额度不足",
    "type": "insufficient_user_quota"
  }
}
  • message:给人看的中文说明,可以直接展示给用户。
  • type:给程序判断的英文标识,代码里按它分支比按 message 判断稳。

状态码

状态码含义常见原因怎么办
401认证失败Key 缺失、打错、已被删除,或这把 Key 自己的额度用完了。检查 Authorization 头是否以 Bearer 开头、Key 是否最新;再看这把 Key 的额度是否已耗尽。
403余额不足账户余额不足以支付本次调用。控制台「钱包」充值后重试。
404路径不对请求地址拼错,比如少了 /v1 或路径大小写不符。对照接口速查页的路径重拼。
429被限流平台侧或上游模型服务商返回了频率限制。降低并发,按指数退避重试(1s、2s、4s…)。
503模型不可用模型名写错,或该模型当前没有可用渠道。核对模型 ID 是否与模型广场一致;换一个模型试试。

该怎么重试

  • 4xx 不要重试:401、403、404 重试多少次都一样,先修问题。
  • 429 要退避:间隔拉长再试,别原地狂刷,会把限流时间越拖越长。
  • 503 可以换模型:多半是那个模型暂时没有可用渠道,换一个能继续干活。
  • 超时同理:长文本请求建议放宽客户端超时,并配合流式输出,避免一直等首字节。

关于当前的频率限制策略,见接口速查页底部的说明。