错误码
接口概述
调用出错时,模型侧错误按原样返回:模型判定请求参数不合法(HTTP 400)或限流(HTTP 429)时,状态码与错误体都与模型返回的一致(文本类为 {"error":{"message","type","param","code"}},DashScope 类为 {"code","message","request_id"}),官方 SDK 可直接解析。
平台侧错误(密钥无效 / 余额不足 / 模型未上架 / 平台内部错误)返回 {"detail": "说明文字"}——同一条路径同时收多种协议(重排收 Cohere 与 DashScope、图像收 OpenAI 与 DashScope),平台侧错误在解析报文前无法判断客户要哪种形状,故用统一格式。视频接口与素材接口是方舟形状错误体(见下方两节)。
状态码
| 状态码 | 含义 | 处理方式 |
|---|---|---|
| 200 | 成功 | - |
| 400 | 参数错误 | 检查请求体(模型名、必填字段、类型);模型侧返回的 param 指出出错字段 |
| 401 | 未认证 | 缺少、拼错或已禁用的 API Key / AK(控制台里创建的 sk- 开头 Key,或素材接口的 AK) |
| 402 | 余额不足 | 在控制台「费用中心」充值(微信扫码)或联系管理员授信(视频与素材接口按方舟口径返回 403,见下) |
| 403 | 无权限 | 访问了仅管理员可用的接口;或视频/素材接口的余额不足(Insufficient.Balance) |
| 404 | 不存在 | 模型未上架 / 已停用;视频任务查不到(方舟形状) |
| 429 | 请求过于频繁 | 触发限流,退避后重试(视频提交类接口 QPS 上限 50) |
| 500 | 服务内部错误 | 请联系管理员 |
| 502 | 平台/链路错误 | 平台侧凭证、权限、路由问题,或模型服务 5xx / 连接失败;正文为 detail 说明(参数不合法不是 502,见上表 400) |
视频接口错误体
视频接口(/v1/videos/* 与 /api/v3/contents/generations/tasks*)的错误统一为:
{
"error": {
"code": "ResourceNotFound",
"message": "The specified resource `cgt-xxx` is not found. Request id: 1f0c…",
"param": "",
"type": "NotFound"
}
}
常用 code:MissingParameter(缺必填,如 model)、AuthenticationError(密钥无效)、Insufficient.Balance(余额不足,HTTP 403)、InvalidEndpointOrModel.NotFound(模型未上架)、ResourceNotFound(任务不存在或不属于当前密钥,HTTP 404)、RateLimitExceeded(限流)、InternalError(内部错误)。响应头带 x-request-id。
任务列表与取消/删除接口不提供(调用返回 404
ResourceNotFound)。
素材接口错误体
素材接口(/ 或 /v1/api/asset)的错误放在 ResponseMetadata.Error(Code / Message):InvalidParameter、NotFound、InvalidApiKey、InsufficientBalance、QuotaExceeded、UnsupportedAction。详见视频生成-Seedance的「素材管理」章节。
示例
未认证(文本/图像类接口):
{ "detail": "API Key 无效或已禁用" }
余额不足(文本/图像类接口):
{ "detail": "余额不足,可在控制台「费用中心」充值,或联系管理员授信" }
余额不足(视频接口,方舟口径 403):
{
"error": {
"code": "Insufficient.Balance",
"message": "余额不足,可在控制台「费用中心」充值,或联系管理员授信",
"param": "",
"type": "Forbidden"
}
}
模型报参数错误(400,错误体就是模型返回的那一份):
{
"error": {
"message": "[] is too short - 'messages'",
"type": "invalid_request_error",
"code": ""
}
}
模型服务故障 / 平台侧凭证问题(502,detail 说明):
{
"detail": "模型服务返回错误 500:{\"error\":{\"message\":\"internal error\"}}"
}
视频任务查不到(404,方舟形状):
{
"error": {
"code": "ResourceNotFound",
"message": "The specified resource `cgt-20260826160420-Tcwwi` is not found. Request id: 1f0c5b8e9a2d4c6f8b0e1a3d5c7f9b2e",
"param": "",
"type": "NotFound"
}
}
常见报错速查
| 报错关键字 | 常见原因 |
|---|---|
| InvalidParameter / InvalidApiKey | 参数不合法、密钥失效 |
| model not found / not supported | 模型名写错(用广场卡片上的名字) |
| RateLimitExceeded | 触发限流:按响应头 Retry-After(秒)退避后重试,勿立刻重发 |
| insufficient_quota | 平台额度不足,请联系管理员 |
| 403 / 拦截页面 | 请求被风控拦截,稍后重试或联系管理员 |