错误处理与排查

先保存错误信息

记录请求时间、接口路径、模型 ID、HTTP 状态码和响应正文；若有请求 ID 也一并保存。不要仅截取客户端一句“失败”。分享日志时隐藏 Authorization、x-api-key 和个人数据。

状态码对照

状态 / 现象	可能原因	下一步
400	参数、消息顺序、工具字段不支持	最小请求验证，再逐项加参数
401	Key 无效、缺失、过期	核对完整 Key 与鉴权头
403	权限、模型限制、IP 限制	检查 Key 与分组
404	路径或模型不存在	检查重复 /v1 和模型 ID
413	请求内容过大	减少图片、文件或历史
429	频率、并发或上游限流	降低并发，按提示等待
500 / 502 / 503	渠道或服务端暂时故障	保留记录，有限重试或联系支持
504 / timeout	客户端、代理或上游超时	查看是否已有成功日志，调整合理超时
返回 HTML	请求落到网页路径	检查最终完整 API URL

标准排查流程

1. 访问 GET /v1/models，确认鉴权与模型可见。
2. 使用同一 Key、同一模型发送一个无工具的简短请求。
3. 检查 Key 分组与模型限制，而不只看账户余额。
4. 基础成功后逐项加回流式、工具、图片和思考参数。
5. 客户端失败时比较其最终 URL 与实际请求模型。

无可用渠道

该提示不一定是模型不存在，也可能是当前分组没有可用路线、渠道暂时停用或模型映射不匹配。模型广场能看到条目也不代表你的 Key 可以在任意分组请求它。请发送错误中的模型和分组给客服核对。

重试策略

鉴权与参数错误不应连续重试。暂时性故障可使用指数退避，例如1秒、2秒、4秒，并限制总次数；服务端有 Retry-After 时遵循该提示。流式已输出一部分内容后，不要无声地重发并把两次结果拼在一起。

联系支持

QQ：318401088。提供时间、模型、路径、状态码、错误正文和脱敏截图。不要把真实 Key 发进群聊、工单公开区或截图。