错误排查

先看 HTTP 状态码，再看响应体里的 message。知梦把上游的原始错误尽量透传出来，绝大多数问题靠这两处就能定位：状态码说明哪一类问题，message 说明具体哪个字段不对。下面按状态码给出「现象 → 原因 → 处理」，再说明不同协议的错误体差异。

错误码速查

状态码	现象	常见原因	处理
401	请求被直接拒绝，返回未授权	Authorization 头缺失、少了 Bearer 前缀、Key 复制时带上空格或换行，或 Key 已被删除 / 重置	重新复制 Key，按 Bearer YOUR_API_KEY 原样填写；确认调用的是服务端环境变量而不是空值
403	鉴权通过但拒绝执行	当前 Key 的分组不包含该模型、账户余额不足、Key 额度已用尽，或该模型未对当前账号开放	在密钥配置里核对分组（如「聚合模型」），确认钱包余额；换用有权限的模型或分组后重试
404	找不到接口或资源	Base URL 用错站（图片站与视频站是两套）、路径少了 /v1、模型 ID 拼错，或查询了不存在的任务 ID	对照 Base URL 与协议 检查地址；模型 ID 逐字符核对；任务查询确认 ID 来自创建响应
413	请求体被网关直接拒收	上传的参考图过大、一次提交太多参考图，或把整张图 Base64 内联进 JSON（Gemini inlineData 尤其容易把请求体撑大）导致超出网关上限	压缩图片、减少参考图数量；能传 URL 的就传公网 URL，不要把大文件内联进 JSON
422	字段能解析但无法处理	必填字段缺失、字段类型不对，或多张参考图 / 编辑参数组合互相冲突（Grok 官方协议明确用 422 表示字段缺失或无法处理）	对照对应模型页的字段表，只提交已列出的字段，检查 prompt、image / images、image[] 等必填项
429	请求被限流	并发过高、短时间内请求频率过高、分组额度或账户额度不足	降低并发并按指数退避重试；查询类 GET 可以重试，创建类 POST 不要立刻重试
5xx	服务端或上游异常	500 / 502 / 503 / 504 多为上游渠道临时不可用、网关等待超时	保存状态码、响应体和 Request ID；创建类请求先核对任务与消费记录再决定是否重提
超时	客户端长时间无响应后断开	生图、视频创建本身耗时较长，或网络抖动；断连不代表服务端没收到请求	先查任务记录或消费明细，不要无条件重发；视频任务已有 ID 就直接轮询
任务失败	创建成功，但查询返回 status: "failed"	提示词被上游拒绝、参考素材 URL 不可直连、时长 / 画质越界、上游生成失败	停止轮询，读 error.message；修正素材或参数后重新创建，不要反复查询同一个失败任务

唯一不能省的一条

网络超时或连接断开不能证明请求没被执行。对 POST /v1/images/generations、POST /v1/images/edits 和视频创建接口做无条件立即重试，会重复生成并重复计费。先查任务和消费记录，再决定是否重提。

各协议的错误体不一样

状态码含义一致，但错误体的结构按协议分成三类，解析代码别写成一种。

OpenAI 兼容协议（ChatGPT 生图、Gemini OpenAI 兼容、Seedream、音频 Chat Completions）：

{
  "error": {
    "message": "具体错误信息",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

展示给用户时取 error.message；type / code 只用于分支判断，不要硬编码成唯一判据。

Gemini 原生协议（/v1beta/models/{model}:generateContent）：

{
  "error": {
    "code": 400,
    "message": "具体错误信息",
    "status": "INVALID_ARGUMENT"
  }
}

这里多了一层 status 字符串：INVALID_ARGUMENT、UNAUTHENTICATED、PERMISSION_DENIED、NOT_FOUND、RESOURCE_EXHAUSTED、INTERNAL、UNAVAILABLE 分别对应上面的 400 / 401 / 403 / 404 / 429 / 500 / 503。原生协议还有几类固定坑：imageSize 里的 K 必须大写、自动比例要省略 aspectRatio 而不是传 auto、参考图必须放在 contents[].parts[] 里。详见 Gemini 原生协议。

视频任务接口（https://movie.zmoapi.cn）：

{"code": "invalid_request", "message": "具体错误原因", "data": null}

提交阶段的参数错误通常直接返回非 2xx（常见 400）。任务本身失败则不是 HTTP 错误，而是查询响应里的 status: "failed"，原因在 error.message。不要用 OpenAI 的 { "error": { ... } } 结构解析视频错误，Veo / Omni 的错误体尤其如此。各视频模型的错误示例见 Wan 3.0、Veo / Omni、MiniMax H3。

视频任务失败怎么读

1. 确认 task_id 来自创建响应，你查的是同一个任务，而不是又创建了一个。
2. 只以 status: "completed" 且存在可用成片地址（优先 content.url）判断成功，progress: 100 不算。
3. failed 时读 error.message；多数是参考素材不可直连（需要登录态、内网地址、网盘分享页），或时长、分辨率、画幅超出该模型允许范围。
4. 成片链接有有效期，成功后就立刻下载转存；过期不是任务失败，重新生成才会再次收费。

还定位不了

按以下顺序补充信息再联系 技术支持：模型 ID、调用协议（OpenAI 兼容 / Gemini 原生 / 视频任务 / Grok 官方）、完整请求路径、HTTP 状态码、响应体中的 message 和 Request ID。常见问题先看 FAQ，价格与计费争议以平台消费记录为准，参照 价格与模型。