错误处理

接入 API 时，建议优先根据 HTTP 状态码判断错误类别，再结合请求参数、认证信息和服务端返回内容定位问题。

日志字段

排查问题时建议记录下面的信息，但不要记录完整密钥：

字段	说明
method	请求方法，例如 POST。
path	请求路径，例如 /v1/chat/completions。
status	HTTP 状态码。
request_id	服务端返回的请求 ID，若响应中提供。
X-Trace-ID / X-Track-Id	客户端生成的请求跟踪 ID。
message	服务端返回的错误消息。

常见 HTTP 状态码

400 Bad Request

表示请求格式或参数有误，常见原因包括：

• JSON 格式不合法
• 必填参数缺失
• model 名称错误
• 字段类型不符合接口要求

优先检查请求体结构、字段名称和参数值是否合法。

401 Unauthorized

表示认证失败，常见原因包括：

• 未传 Authorization 请求头
• Authorization 格式不正确
• API Key 无效、已过期或已被撤销

优先检查 Authorization: Bearer YOUR_API_KEY 是否完整且正确。

403 Forbidden

表示当前身份无权访问目标资源，常见原因包括：

• Key 没有对应接口或模型权限
• 账号被限制
• 当前入口不允许访问该能力

这类问题通常不是重试就能解决，需要先确认权限配置。

429 Too Many Requests

表示请求频率超出限制，常见原因包括：

• 短时间内并发过高
• 同一 Key 请求过于密集
• 平台对模型或账号有速率限制

建议降低请求频率，并在客户端实现退避重试。应优先遵守响应中的 Retry-After，且任何退避时间都不得短于具体接口页面规定的最低查询间隔。

500 Internal Server Error

表示服务端内部错误，常见原因包括：

• 服务临时异常
• 上游模型服务波动
• 平台内部处理失败

如果请求参数确认无误，可稍后重试；若持续出现，应联系平台支持并附上请求时间和错误信息。

建议的排查顺序

建议按下面的顺序排查：

1. 先看 HTTP 状态码，判断是参数问题、认证问题、权限问题还是服务端问题
2. 检查请求地址、方法和请求头是否正确
3. 检查请求体 JSON 是否合法，必填字段是否完整
4. 核对 model、接口路径和能力类型是否匹配
5. 确认 API Key 是否有效，且具备目标接口权限
6. 对 429 和 500 场景查看是否存在瞬时波动，再决定是否重试

重试建议

• 对 400、401、403，应先修正请求或权限问题，不建议盲目重试
• 对 429，优先遵守 Retry-After 和具体接口最低查询间隔；仅当接口未规定更长间隔时，才使用 1 秒、2 秒、4 秒等指数退避
• 对 500，可以做有限次数重试，避免无限循环
• 如果是异步任务接口，重试前先确认任务是否已经创建成功，避免重复提交

异步任务排查

图片异步、视频生成和素材审核接口通常会先返回任务 ID，再通过查询接口获取最终结果。排查这类问题时需要额外确认：

• 创建任务接口是否已经返回 task_id 或 id
• 是否因为客户端重试重复创建了多个任务
• 查询频率是否超过文档建议
• 任务状态是等待中、处理中、成功、失败还是取消（cancelled、canceled）
• 取消属于终态，应停止轮询，且不默认重试
• 结果 URL 是否已经过期
• 回调地址是否公网可访问，且能正常接收平台请求

当你需要记录错误日志时，建议保存状态码、请求时间、请求路径和服务端返回的错误消息，但不要在日志中输出完整 API Key。

完整的状态分类、轮询、回调、幂等和创建请求重试规则，请查看异步任务指南。