错误响应

所有协议的错误都收敛成同一形态：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202611011236544117861678268d9d6E26uSeOq)",
    "type": "new_api_error"
  }
}

字段说明

字段	说明
code	上游错误码，可能为空串
message	人读信息，末尾带 request id
type	错误类别，中转层统一为 new_api_error

:::tip 排障必备 把 message 里的 request id 一起提供，我们能直接定位到那一次请求的 渠道、上游、扣费记录。没有它只能靠时间猜。 :::

HTTP 状态码

状态码	含义	常见原因
400	请求格式错误	JSON 不合法、缺必填字段
401	鉴权失败	key 错、已禁用、未带鉴权头
403	无权限	分组不允许该模型
404	路径不存在	用了未实现的端点（如 /v1/files）
429	限流或额度耗尽	请求过快 / 令牌额度用完
500	上游异常	上游模型报错
502/503	上游不可用	上游临时故障

典型错误文本

Invalid token

key 无效。检查是否复制完整、是否已被禁用。

model not found

模型名不在你的分组内。用 /v1/models 确认可用清单。

insufficient quota

令牌额度或账户余额不足。

context length exceeded

输入超过模型上下文窗口。

重试策略

情况	建议
429	指数退避重试，别立刻重打
500 / 502 / 503	可重试 1~2 次，间隔递增
400 / 401 / 403 / 404	不要重试，改请求或改配置
流式中途断开	可从最后完整片段续，但收费已产生

完整清单见 错误码。