错误码

API 网关的响应格式、常见 HTTP 状态码，以及错误响应中 type 与 code 字段的取值说明。

API 网关的错误响应遵循 OpenAI 兼容格式：HTTP 状态码表达错误大类，响应体中的 error.type 与 error.code 提供可程序化处理的具体原因。

错误响应格式

推理类接口（聊天、图片、视频、音频等）出错时返回非 200 的 HTTP 状态码，响应体为：

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": ""
  }
}

字段	类型	说明
`message`	string	人类可读的错误说明，可能按请求语言翻译
`type`	string	错误大类，由 HTTP 状态码推导，取值见下文 type 取值
`code`	string	具体错误码，取值见下文 code 取值；部分错误可能为空字符串
`param`	string	相关请求参数名，多数情况下为空

管理类接口（/api/ 下的控制台接口）风格不同：业务错误通常也返回 HTTP 200，通过 success 字段区分：

{
  "success": false,
  "message": "错误说明",
  "data": null
}

Seedance 素材库接口使用 ResponseMetadata.Error 结构，详见 Seedance 素材库。

状态码	含义	常见场景
`200`	成功	请求正常完成；管理类接口的业务错误也返回 200
`400`	请求错误	请求体非法 JSON、缺少必填参数、参数取值非法
`401`	未认证	未提供 API Key、Key 无效或已禁用
`403`	无权限	Key 无权访问该模型/分组、IP 不在令牌白名单、用户被封禁、额度不足
`404`	不存在	请求路径不存在，或异步任务 ID 不存在
`408`	请求超时	上游处理超时
`413`	请求体过大	超过 256 MB 请求体上限，错误码 `request_too_large`
`429`	限流	触发全局限流或模型 RPM/TPM 限制，请降低频率并重试
`500`	服务内部错误	网关内部错误
`501`	未实现	调用了网关不支持的接口路径，错误码 `api_not_implemented`
`502` / `503`	上游错误	上游模型服务返回错误或不可用
`504`	上游超时	上游模型服务响应超时

error.type 由 HTTP 状态码推导，是稳定的错误大类：

error.code 是更具体的机器可读错误码。常见取值如下。

code	说明
`invalid_api_key`	API Key 缺失、无效或已删除（401 的默认 code）
`access_denied`	无权访问请求的资源、分组或代理域名

code	说明
`invalid_request`	请求参数错误（400 的默认 code）
`invalid_json`	请求体不是合法 JSON
`invalid_type`	字段类型错误
`missing_parameter`	缺少必填参数
`bad_request_body`	请求体内容不符合接口要求
`read_request_body_failed`	读取请求体失败
`convert_request_failed`	请求格式转换失败
`request_too_large`	请求体超过 256 MB 上限（HTTP 413）
`remote_fetch_failed`	拉取请求中的远程文件（如图片 URL）失败
`unsupported_response_format`	不支持的响应格式参数

code	说明
`model_not_found`	请求的模型不存在或未对当前令牌开放
`prompt_blocked`	提示词被上游安全策略拦截
`sensitive_words_detected`	内容触发敏感词检测
`channel:no_available_key`	渠道无可用密钥
`channel:invalid_key`	渠道密钥无效
`channel:model_mapped_error`	模型映射配置错误
`channel:param_override_invalid`	渠道参数覆盖配置非法
`channel:header_override_invalid`	渠道请求头覆盖配置非法
`channel:aws_client_error`	AWS 渠道客户端错误
`channel:response_time_exceeded`	渠道响应时间超过限制

channel:* 类错误表示某个上游渠道失败，网关通常会自动切换到其他渠道重试；只有当所有可用渠道都失败时才会返回给客户端。

code	说明
`insufficient_user_quota`	账户额度不足，请充值后重试（HTTP 403）
`pre_consume_token_quota_failed`	预扣费失败，通常是额度不足以覆盖本次请求的预估费用（HTTP 403）

视频生成等异步任务接口（如 Seedance、Kling）在创建任务时可能返回上述错误；任务创建成功后，处理失败不会修改任务查询接口的 HTTP 状态码，而是在任务结果的 error 字段中体现：

{
  "id": "task-id",
  "status": "failed",
  "error": {
    "code": "上游错误码",
    "message": "失败原因"
  }
}

轮询任务时应以 status 字段判断任务状态，failed 时读取 error 获取原因。