invalid character '<' looking for beginning of value（或响应体以 < 开头） | Base URL / 路径填错，返回了 HTML 登录页或官网页 | 确认网关地址与平台前缀（如 /suno/...、/kling/v1/...、/v1/video/...），响应须为 JSON |
| 401 | API Key 无效、过期、未传 Authorization | 使用 Bearer sk-...；在控制台确认令牌状态 |
| 403 | 无权限、令牌模型限制、分组不允许、IP 不在白名单 | 检查令牌可用模型 / 分组 / allow_ips |
400 / invalid_request | 参数缺失、类型错误、JSON 无法解析 | 对照该接口 OpenAPI 的 required / enum / 示例 |
404 / task_not_exist | 路径错误，或 task_id 不存在 / 不属于当前 Key | 核对 path；确认提交返回的 ID，勿用错字段 |
| 429 | 触发限流 | 退避重试；降低并发与轮询频率（建议 3–10s） |
| 408 / 客户端超时 | 提交或轮询 HTTP 超时过短 | 提交可适当加大 timeout；生成本身靠轮询，勿指望单次请求等出片 |
| 502 / 503 / 504 | 网关或上游暂不可用 / 超时 | 指数退避重试；高峰期降并发或换模型 |
| HTTP 200 但 body 报错 | 业务失败写在 JSON 内 | 解析 success / code / message / error，勿仅凭 HTTP 码判断成功 |
模型不存在 / 无可用渠道 (channel_not_found) | 模型名拼写错误，或当前分组/令牌无对应渠道 | 对照控制台「支持模型」与令牌分组；必要时换分组或模型 |
| 余额 / 额度不足 | 预扣费失败 | 充值或提高令牌额度后再提交 |
枚举 literal_error | 请求体 enum（如 Suno mv）不在上游允许列表 | 对照接口文档 enum / x-error-playbook 与渠道实测 |
| Open / Legacy 字段混用 | 用错任务 ID 字段或轮询路径 | Open 侧常见 taskBatchId；Legacy 常见 data.task_id；提交与查询必须成对、协议一致 |
task_id 与 clip_id 混用（Suno 等） | 轮询用了续写 ID，或续写用了任务 ID | 轮询用提交返回的 task_id；续写 / 补段用 fetch 结果中的 clip_id |
| 提交成功但一直 pending / processing | 上游排队、渠道拥堵或异常 | 按建议间隔继续轮询；业务侧设总超时（如 10–30 分钟）；持续异常带任务 ID 联系运维查渠道日志 |
任务超时失败（fail_reason 含 timed out 等） | 超过平台任务超时（常见约数十分钟量级） | 查看 fail_reason；失败终态通常会退还本次预扣额度；勿重复高频重提同一失败任务 |
终态 failed / error | 上游生成失败、参数不合规、内容审核等 | 读 message / error / fail_reason；按文案改 prompt / 素材后重试 |
| 参考图 / 素材 URL 失效 | 图床临时链过期，上游拉取失败 | 换可公网访问的稳定地址，或按图床说明转存后再传 |
| 图生 / 多模态任务失败 | 图片过大、非图片 MIME、格式不受支持 | 按接口限制压缩与转码后再提交 |
| 轮询路径 404 或状态字段为空 | 提交接口与查询接口不成对（如 Kling 各任务类型 path 不同） | 以门户该操作的 OpenAPI 为准，成对使用提交 + 查询 path |
| 重复提交同一任务 | 客户端超时后重试导致多扣费 / 多任务 | 同一业务请求先查已有 task_id；仅在文档允许时重新提交 |
