错误处理

请求无法生成音频时，API 会返回包含 error_code、error_message、succeed 和 data 的 JSON 错误。error_code 是业务错误码，不是 HTTP 状态码；error_message 按 Accept-Language 返回（默认英文，中文请求返回中文）。下面示例未传 Accept-Language，因此保留接口默认的英文原始字段值。错误响应不包含 trace_id。

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

HTTP 状态	业务 `error_code`	含义	处理方法
`400`	`10001`	请求内容无效或选项不受支持	检查请求内容后重试
`400`	`10013`	文本超过 500 个加权字符上限	缩短文本；每个中文字符按 2 个字符计，其他 Unicode 字符按 1 个字符计
`400`	`10023`	输入中没有可合成内容	请输入有效文字或支持的事件标签
`401`	`10003`	API Key 缺失或无效	检查 API Key
`402`	`20003`	账户余额不足	充值后重试
`403`	`10004`	当前项目无法使用语音合成	检查项目可用功能
`429`	`10005` 或 `10014`	请求次数达到限制	稍后重试
`500`	`10000`	服务发生未预期错误	重试；如果持续发生，请联系支持
`503`	`20002`	服务暂时不可用	稍后重试
`504`	`10006`	服务在返回音频前超时	稍后重试

音色克隆错误

音色管理接口成功时返回 HTTP 200；失败时返回非 2xx HTTP 状态码及标准 JSON 响应体。请同时检查 HTTP 状态码和 succeed、error_code。

HTTP 状态	业务 `error_code`	含义	处理方法
`409`	`10017`	自定义音色数量已达上限	删除不再使用的音色后重试
`409`	`10018`	`voice_id` 已存在或被占用	更换 `voice_id`
`409`	`10019`	生成或提交的音色 ID 与已有音色冲突	重试或更换 `voice_id`
`413`	`20010`	文件超过对应接口的大小限制	文件上传不超过 50 MiB；音色克隆参考音频不超过 20 MiB
`400`	`20012`	参考音频格式无效或无法处理，包括内容损坏或没有音频流	上传受支持且可读取的参考音频文件
`400`	`20015`	参考音频超过 60 秒	上传 3–60 秒的参考录音
`400`	`20016`	参考音频不足 3 秒或没有足够的可用语音	上传清晰连续的语音，避免纯静音或噪声
`400`	`20017`	参考语音的停顿过长	上传包含更连续语音的录音

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

音色克隆错误​

音色克隆错误