错误码与排查

排查时先记录：HTTP 状态码、平台返回的请求标识、模型 ID、任务 ID、素材 ID 和原始错误码。

不要记录 API Key、真人会话 Token 或完整素材下载地址；提交给平台支持前请先脱敏。

HTTP 状态含义

404 有三种成因，不要一律当成「ID 写错了」

这是排查时最容易误判的一点：

拿到 404 时，先确认路径与方法是否匹配，再怀疑 ID。

查不到视频任务返回 400，不是 404

这一处与其他接口不一致，需要特别注意：

视频任务查询用 400 + 顶层 {code, message, data} 结构返回， 既不是 404，也不是下面说的 error 对象结构。

错误响应有三种结构

1. 模型 / 图片 / 视频生成接口 —— error 对象

失败时返回 HTTP 非 2xx，并带一个 error 对象：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code 可能是空字符串。 实测：鉴权失败与请求体 JSON 无法解析时 code 都是 ""。 不要用 code 是否为空来判断「是不是错误」，应以 HTTP 状态码为准，并优先读 message。

type 不是稳定分类字段。 需要分类时请读 code，不要依赖 type 的取值。

2. 素材库接口 —— 顶层 code

返回 HTTP 非 2xx，code 与 HTTP 状态一致：

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. 视频任务查询 —— 顶层 code 字符串

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

注意这里的 code 是字符串 task_not_exist，不是数字。

request id：排查问题的关键标识

平台把 request id 直接写在 error.message 里，不需要去 header 里找：

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

一行命令取出：

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

提交工单时附上这个 request id，可以大幅缩短定位时间。

鉴权失败

API keys 缺失、错误或已失效时，所有接口都返回 HTTP 401 和：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

注意 code 为空字符串——这正是上面提醒「不要依赖 code」的原因。

模型与生成错误

素材库错误

素材审核未完成不是错误：查询返回 200，status 为 Processing，继续轮询同一个素材 ID 即可。

推理模型输出为空也不是 HTTP 错误：如果返回 200、finish_reason 为 length，且 usage.completion_tokens_details.reasoning_tokens 已占满输出上限，应提高输出额度或改用非推理模型。

真人授权错误

限流与重试

• 429 表示请求过于频繁，按提示退避重试，不要并发重试；
• 素材状态建议 5～10 秒查询一次，视频任务建议 5～15 秒一次；
• 只对 429 和短暂的 5xx 重试；400 / 401 / 403 / 404 直接修正请求；
• 重试前先按任务 ID / 素材 ID 查询，避免重复创建和重复计费。

快速自检

1. Authorization 是否为 Bearer <API Key>，Key 是否仍在启用状态；
2. 请求域名是否为控制台当前指定的地址（默认 https://locopalai.com，海外模型可能为 https://us-api.locopalai.com）；
3. model 是否来自 /v1/models 的 data[].id；
4. 素材 status 是否已经是 Active；
5. 参考图片 / 视频地址是否是公网可直接访问的 http(s) 地址，且不依赖 Cookie 或 Referer；
6. 同一个任务 / 素材是否重复提交过。

提交支持时请附上

• 请求时间与接口路径；
• HTTP 状态码与完整响应体（API Key 打码）；
• 平台返回的请求标识、任务 ID 或素材 ID；
• 涉及的模型 ID 与参数；
• 可复现的最小请求示例。