跳到主要内容

错误处理

通用错误格式​

API 的 JSON 错误响应包含 error_code、error_message、succeed 和 data。error_code 是业务错误码,不是 HTTP 状态码。

{
"error_code": 10003,
"error_message": "Unauthorized",
"succeed": false,
"data": null
}

请同时检查 HTTP 状态码和业务结果。即使 HTTP 状态为 200,succeed: false 和非零 error_code 仍表示业务失败。data 可包含附加错误信息,也可能为 null。

错误提示语言​

语音合成和声音设计的 error_message 默认使用英文。传入 Accept-Language: en 返回英文,传入 Accept-Language: zh-CN 返回中文。该请求头仅控制错误提示的语言。

语音合成错误​

HTTP 状态业务 error_code含义处理方法
40010001请求内容无效或选项不受支持检查请求内容后重试
40012913音色不支持所选模型,data.errorKey: VOICE_MODEL_INCOMPATIBLE用相同 model_id 重新查询音色,选择返回的 ID
40010013文本超过 500 个加权字符上限缩短文本;汉字(含扩展区)、平假名、片假名、韩文及长音符 ー/ー 计 2,CR/LF 不计,其他 Unicode 码点计 1;250 个纯中日韩字符允许,251 个拒绝
20010023输入中没有可合成内容请输入有效文字或支持的事件标签
40110003API Key 鉴权失败,包括 Key 缺失或无效、组织或项目已禁用检查 API Key 及组织、项目状态
40220003账户余额不足充值后重试
40310004没有执行该操作或访问该资源的权限检查 API Key 权限与组织成员状态,恢复权限后再重试
42910005 或 10014请求次数达到限制稍后重试
50010000服务发生未预期错误重试;如果持续发生,请联系支持
50320002服务暂时不可用稍后重试
50410006服务在返回音频前超时稍后重试

如果流式生成意外中断,联系支持时请提供 HTTP 状态、接口路径和包含时区的大致发生时间。

音色克隆错误​

HTTP 状态业务 error_code含义处理方法
40010001克隆参数不合法或参考语音语言不受支持使用中文、英文、日文或韩文参考语音,并检查其他参数
20012903组织声音槽位已满,succeed: false、data.errorKey: VOICE_SLOTS_FULL删除不再使用的自定义音色以释放槽位,或升级套餐后再创建
40910018voice_id 已存在于当前组织或被系统占用更换 voice_id,原音色保持不变
40410002参考音频不存在或已被删除重新上传音频并传入新的 ref_audio;不要原样反复重试
40910019生成或提交的音色 ID 与已有音色冲突重试或更换 voice_id
41320010文件超过对应接口的大小限制文件上传不超过 50 MiB;音色克隆参考音频不超过 20 MiB
40020012参考音频格式无效或无法处理,包括内容损坏或没有音频流上传受支持且可读取的参考音频文件
40020015参考音频超过 60 秒上传 3–60 秒的参考录音
40020016参考音频不足 3 秒或没有足够的可用语音(含未检测到可用语音)上传清晰连续的语音,避免纯静音或噪声
40020017参考语音的停顿过长上传包含更连续语音的录音

保存音色时声音槽位已满的业务响应示例(HTTP 200):

{
"error_code": 12903,
"error_message": "声音槽位不足,请升级订阅或释放槽位。",
"succeed": false,
"data": {
"errorKey": "VOICE_SLOTS_FULL",
"details": null
}
}

声音设计错误​

生成和保存接口的业务失败可能返回 HTTP 200,错误响应的 data 为 null。保存新音色时,声音槽位不足的错误码为 12903。10005 表示请求频率或生成执行容量达到限制;容量拒绝不生成候选、不计费。模型或依赖服务暂时不可用则返回 20002。

完整错误码、处理方法与重试说明见声音设计 API:错误与恢复。