错误处理与请求追踪

错误响应的三种形态

平台存在三种不同的错误响应形态，适用端点各不相同。按下表区分，不要假设所有端点共用一种结构：

模型接口（/v1、/v2）

错误响应统一为 OpenAI 风格的 error 对象：

{
  "error": {
    "code": "model_not_found",
    "message": "模型 xxx 暂无可用渠道，请稍后再试 (request id: 20260728144017316963600KfI3f8bQ)",
    "type": "jimu_api_error"
  }
}

type 的取值：

code 非空时是稳定的机器可读标识，适合程序判断。常见取值：

Anthropic 原生接口的错误变体

/v1/messages 等 Claude 原生端点返回 Claude 风格的错误结构：

{
  "type": "error",
  "error": {
    "type": "jimu_api_error",
    "message": "未提供令牌 (request id: 20260728144017307942003YcfgsXq)"
  }
}

error.type 的取值与上表一致，message 同样附带 request id。

任务类接口（异步任务）

视频生成等异步任务端点（任务提交与结果查询，如 /v1/video/generations/{task_id}、/v1/videos/{task_id}） 不使用嵌套 error 对象，而是返回顶层扁平信封：

{
  "code": "task_not_exist",
  "message": "task_not_exist",
  "data": null
}

• 顶层字段为 code / message / data，没有 error 包装、没有 type 字段
• 任务不存在时 HTTP 状态码是 400 而非 404，不要用状态码区分「路由不存在」与「任务不存在」
• 任务提交失败（如配额不足 403 quota_not_enough、上游负载饱和 429）同样是此信封
• message 不附带 request id；报障时请提供 task_id 与请求时间

常见任务类 code：task_not_exist（任务不存在）、task_origin_not_exist（上游任务已不存在）、 quota_not_enough（配额不足）。

管理接口（/api）

管理接口不使用 error 对象，而是返回：

{
  "success": false,
  "message": "无权进行此操作，未登录且未提供 access token"
}

判断管理接口成败以 success 布尔值为准，不要只依赖 HTTP 状态码： 部分校验失败场景 HTTP 状态码仍为 200，仅靠 success: false 标识失败。

常见 HTTP 状态码

重试策略：429 与 5xx 可指数退避重试（建议 1s、2s、4s，最多 3 次）； 400、401、403 属于确定性错误，修正请求前不要重试。

关于限流的稳定口径：具体阈值由账号与平台配置动态决定，不承诺固定 RPM/TPM 值； 响应不提供 Retry-After 或 X-RateLimit-* 头，不要依赖它们。 触发 429 时按指数退避并加入随机抖动（jitter），同时收敛客户端并发。

request id

每个请求都会分配唯一 request id，通过两种方式返回：

• 响应头 X-Jimu-Request-Id——成功与失败响应都携带，应优先从这里读取
• 错误响应 message 末尾的 (request id: ...) 后缀——与响应头是同一个 ID，仅在出错时出现

排查问题或联系支持时，请提供 request id 与大致请求时间， 平台可据此在服务端日志中精确定位该次请求的完整链路（含上游渠道与原始响应）。