API 错误码与排障

本页统一说明调用失败时应如何判断和处理。HTTP 状态码、响应中的 error / message / success 字段，以及上游渠道返回的具体错误文本都可能随接口和渠道变化；请不要把某个上游错误码当作永久不变的客户侧约定。

先按这个顺序判断

1. 查看 HTTP 状态码。
2. 查看完整响应中是否有 error、失败消息或 success: false。即使 HTTP 是 200，只要业务响应表示失败，也应按失败处理。
3. 在使用日志中按 request_id、时间、模型和接口核对请求记录。

常见状态与处理

• 400 请求无效：核对 Base URL、接口路径、协议、JSON 格式和必填参数。先用短文本、非流式请求复现，不要一次加入超大上下文、文件或图片。
• 401 未授权：确认请求头为 Authorization: Bearer <API Key>，Key 已完整复制且没有多余空格、错误前缀或失效状态。不要在截图、工单或聊天中发送完整 Key。
• 403 无权限：检查账号或 Key 是否被禁用，以及模型、分组或 IP 限制是否允许本次调用；客户无法自行解除的限制请联系管理员。
• 404 接口或模型不存在：使用平台公开模型名，而不是上游内部名称；同时核对客户端没有重复拼接 /v1 或填写错误接口路径。
• 429 限流或配额不足：停止并发重试，等待后用一次短请求确认；检查可用额度、速率限制和并发限制。
• 5xx、网络错误或超时：可能来自上游、渠道或网络。保留 request_id 后做一次短、低成本重试；不要对同一失败请求无限重放。
• 非流式成功、流式失败：先确认非流式短请求正常，再检查客户端、代理和所选渠道是否都支持流式响应及是否存在响应缓冲。

联系支持前请准备

提供发生时间及时区、request_id、接口路径、平台公开模型名、客户端名称和版本、是否使用流式、HTTP 状态码，以及已脱敏的响应文本或截图。不要提供 API Key、密码、完整支付信息或不必要的提示词和业务数据。