错误码与排查

错误响应结构

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error"
  }
}

状态码	含义	建议处理
`400`	请求格式或参数无效	检查 JSON 或 multipart 格式、必填字段以及所选模型支持的能力。
`401`	API Key 缺失、无效或已失效	确认鉴权头、密钥内容和过期时间；不要在 Bearer 前后加入额外引号。
`403`	API Key 权限限制	检查模型白名单、IP 白名单或其他密钥限制。
`404`	模型或异步任务不可用	使用 /v1/models 返回的模型 ID，并确认任务 ID 属于当前账号。
`429`	频率限制或额度不足	降低请求频率并检查密钥限制、账户额度和钱包状态，再按退避策略重试。
`500`	平台内部错误	保留 X-Request-Id，稍后重试，并在控制台请求记录中定位。
`502`	上游 Provider 请求失败	检查模型路线可用性，进行有限次数的退避重试。
`503`	服务或模型路线暂时不可用	稍后重试；持续出现时更换可用模型或检查 Provider 状态。

网关通过 X-Request-Id 响应头返回请求 ID。反馈问题时请保留该值，并在登录后的控制台用量或请求记录中定位对应调用。

流式连接建立后发生的错误可能作为 SSE 事件返回，而不是新的 HTTP 错误响应。客户端需要同时处理非 2xx 响应、流中错误事件、连接超时和中途断开。空闲连接可能收到注释心跳。