错误码

接口概述

调用出错时,模型侧错误按原样返回:模型判定请求参数不合法(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 / 拦截页面请求被风控拦截,稍后重试或联系管理员