错误码
出错时返回的不是 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 可以换模型:多半是那个模型暂时没有可用渠道,换一个能继续干活。
- 超时同理:长文本请求建议放宽客户端超时,并配合流式输出,避免一直等首字节。
关于当前的频率限制策略,见接口速查页底部的说明。