错误处理
通用错误格式
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 | 含义 | 处理方法 |
|---|---|---|---|
400 | 10001 | 请求内容无效或选项不受支持 | 检查请求内容后重试 |
400 | 12913 | 音色不支持所选模型,data.errorKey: VOICE_MODEL_INCOMPATIBLE | 用相同 model_id 重新查询音色,选择返回的 ID |
400 | 10013 | 文本超过 500 个加权字符上限 | 缩短文本;汉字(含扩展区)、平假名、片假名、韩文及长音符 ー/ー 计 2,CR/LF 不计,其他 Unicode 码点计 1;250 个纯中日韩字符允许,251 个拒绝 |
200 | 10023 | 输入中没有可合成内容 | 请输入有效文字或支持的事件标签 |
401 | 10003 | API Key 鉴权失败,包括 Key 缺失或无效、组织或项目已禁用 | 检查 API Key 及组织、项目状态 |
402 | 20003 | 账户余额不足 | 充值后重试 |
403 | 10004 | 没有执行该操作或访问该资源的权限 | 检查 API Key 权限与组织成员状态,恢复权限后再重试 |
429 | 10005 或 10014 | 请求次数达到限制 | 稍后重试 |
500 | 10000 | 服务发生未预期错误 | 重试;如果持续发生,请联系支持 |
503 | 20002 | 服务暂时不可用 | 稍后重试 |
504 | 10006 | 服务在返回音频前超时 | 稍后重试 |
如果流式生成意外中断,联系支持时请提供 HTTP 状态、接口路径和包含时区的大致发生时间。
音色克隆错误
| HTTP 状态 | 业务 error_code | 含义 | 处理方法 |
|---|---|---|---|
400 | 10001 | 克隆参数不合法或参考语音语言不受支持 | 使用中文、英文、日文或韩文参考语音,并检查其他参数 |
200 | 12903 | 组织声音槽位已满,succeed: false、data.errorKey: VOICE_SLOTS_FULL | 删除不再使用的自定义音色以释放槽位,或升级套餐后再创建 |
409 | 10018 | voice_id 已存在于当前组织或被系统占用 | 更换 voice_id,原音色保持不变 |
404 | 10002 | 参考音频不存在或已被删除 | 重新上传音频并传入新的 ref_audio;不要原样反复重试 |
409 | 10019 | 生成或提交的音色 ID 与已有音色冲突 | 重试或更换 voice_id |
413 | 20010 | 文件超过对应接口的大小限制 | 文件上传不超过 50 MiB;音色克隆参考音频不超过 20 MiB |
400 | 20012 | 参考音频格式无效或无法处理,包括内容损坏或没有音频流 | 上传受支持且可读取的参考音频文件 |
400 | 20015 | 参考音频超过 60 秒 | 上传 3–60 秒的参考录音 |
400 | 20016 | 参考音频不足 3 秒或没有足够的可用语音(含未检测到可用语音) | 上传清晰连续的语音,避免纯静音或噪声 |
400 | 20017 | 参考语音的停顿过长 | 上传包含更连续语音的录音 |
保存音色时声音槽位已满的业务响应示例(HTTP 200):
{
"error_code": 12903,
"error_message": "声音槽位不足,请升级订阅或释放槽位。",
"succeed": false,
"data": {
"errorKey": "VOICE_SLOTS_FULL",
"details": null
}
}
声音设计错误
生成和保存接口的业务失败可能返回 HTTP 200,错误响应的 data 为 null。保存新音色时,声音槽位不足的错误码为 12903。10005 表示请求频率或生成执行容量达到限制;容量拒绝不生成候选、不计费。模型或依赖服务暂时不可用则返回 20002。
完整错误码、处理方法与重试说明见声音设计 API:错误与恢复。