错误码说明
聚模平台（AISP）所有接口统一返回 { code, msg, data } JSON 结构，业务码 code 位于响应体，HTTP 状态码通常为 200。 本文档列出常见业务错误码及其含义，帮助开发者快速定位问题。
响应格式
成功与失败均为上述统一结构：
// 成功响应
{
"code": 200,
"msg": "success",
"data": { ... }
}
// 失败响应
{
"code": 400,
"msg": "错误描述信息"
}通用错误码
| code | 含义 | 触发场景 | 解决方案 |
|---|---|---|---|
| 200 | 成功 | 请求处理成功 | — |
| 0 | 通用错误 | 部分接口对必填参数缺失返回（如 Chat 缺 model / messages） | 检查请求参数是否完整 |
| 400 | 参数错误 | 参数缺失、格式错误，或输入不满足模型能力（缺必填参考、分辨率不支持等） | 按 msg 中的友好提示修正或切换模型 |
| 401 | 鉴权失败 | 未提供 / 无效 / 已过期的 API Key，或用户不存在 | 检查 Authorization: Bearer <key> 是否正确 |
| 402 | 余额 / 额度不足 | 账户余额不足、令牌额度不足或已用完 | 充值余额或更换/续期 API Key |
| 403 | 权限受限 | IP 不在白名单、模型不是当前能力类型（如非图片模型）等 | 将 IP 加入白名单，或使用对应能力的模型 |
| 404 | 资源不存在 | 模型不存在、任务不存在 | 检查模型名 / 任务 ID 是否正确 |
| 500 | 服务端 / 上游错误 | 平台内部异常、上游模型异常。音频接口的地缺参/余额不足等业务错误也统一归为 500 | 稍后重试，或切换其他模型 |
输入容错提示（模型能力 / 参考输入）
平台在调用上游前会基于模型能力做输入校验。缺必填输入、传入某模型不支持的多模态输入、或分辨率不在支持档位时，返回友好 400 提示（而非内部报错），方便客户端直接向用户展示并切换模型。
| 错误信息（示例） | 触发场景 | 解决方案 |
|---|---|---|
| 该模型不支持图片输入，请选择支持图片的模型 | 当前 Chat 模型不支持图片（Vision） | 切换支持图片输入的模型，或去除图片内容 |
| 该模型不支持视频/音频输入，请选择支持视频/音频的模型 | 当前 Chat 模型不支持视频 / 音频输入 | 切换到支持对应输入的多模态模型 |
| 该模型必须提供 首帧图(参数 first_frame_url) | 图生视频模型未传首帧图 | 补充 first_frame_url 首帧图 |
| 该模型必须提供 参考图(参数 image_url) | 参考生视频模型未传参考图 | 补充 image_url / image_urls |
| 该模型必须提供 待编辑视频(参数 video_url) | 视频编辑模型未传待编辑视频 | 补充 video_url |
| 该模型不支持 2160P 分辨率，支持档位：480P/720P/1080P | 视频 / 图片分辨率不在模型支持档位 | 改用模型支持的档位 |
错误响应示例
// 鉴权失败
{ "code": 401, "msg": "无效的API令牌" }
// 余额不足
{ "code": 402, "msg": "账户余额不足，请充值后使用" }
// IP 白名单
{ "code": 403, "msg": "IP地址不在白名单内" }
// 模型不存在
{ "code": 404, "msg": "Model not found" }
// 输入容错
{ "code": 400, "msg": "该模型不支持图片输入，请选择支持图片的模型" }
{ "code": 400, "msg": "该模型必须提供 首帧图(参数 first_frame_url)" }
// 上游异常
{ "code": 500, "msg": "Image generate failed" }错误处理建议
- 4xx 错误：客户端错误，应检查参数、鉴权与模型能力，通过代码逻辑修复
- 5xx 错误：服务端 / 上游问题，建议短暂间隔后重试 1~2 次或切换模型
- 400 容错提示：可直接向用户展示 msg，或自动切换支持该输入的模型
联系技术支持
如遇到无法自行解决的错误，请提供以下信息联系技术支持：
- 错误的完整响应内容（code + msg）
- 请求的接口地址和请求参数
- 请求时间
- API Key（部分脱敏即可）
提供完整的错误信息可以帮助技术支持团队更快定位和解决问题。