错误代码与排查

先记录发生时间、HTTP 状态码、模型、端点和请求 ID。隐藏 API Key 后再提交排查。

常见状态码

状态码	常见原因	建议处理
400	JSON、参数或请求体格式错误	对照端点示例，检查 model、stream 和 Content-Type
401	未带 Key、Key 错误或已失效	重新创建/设置 Key，检查认证头
403	账户、项目或上游权限不足	更换支持该能力的模型或联系管理员
404	路径错误、模型不存在或平台不支持该端点	检查 /v1 是否重复，并重新拉取模型列表
409	请求状态冲突	避免重复提交，按响应说明处理
429	并发、速率、模型容量或上游限流	尊重 Retry-After，退避重试或稍后再试
500	网关内部异常	保留请求 ID，稍后重试并反馈
502	上游返回无效响应或连接失败	稍后重试；持续发生时反馈请求 ID
503	没有兼容可用账号或服务暂不可用	更换模型、稍后重试或联系管理员
504	上游超时	降低请求复杂度或延长客户端超时

Selected model is at capacity

表示该模型当前没有可立即接单的兼容上游账号，通常与账号池繁忙、限流窗口或容量有关，而不是本地配置文件损坏。

处理顺序：

1. 等待数秒后按指数退避重试。
2. 确认模型仍在 /v1/models 中。
3. 有替代模型时临时切换。
4. 持续发生时提供时间、模型和请求 ID 给管理员。

首 Token 时间偏高

首 Token 时间包括网络连接、排队、账号选择、上游握手、模型推理前置处理和工具准备。建议：

• 使用流式响应改善用户感知。
• 避免每次请求都携带过大的上下文。
• 对比关闭超高 reasoning effort 后的结果。
• 连续测试多次并看 P50/P95，不要只看一次请求。
• 区分“连接建立慢”和“上游模型开始输出慢”。

生成图片但客户端不显示

先查看原始 JSON。存在 b64_json 说明生成成功，问题在客户端展示；完全没有图像字段则继续检查模型、分组与请求格式。参见图像生成与编辑。