错误码说明
调用接口时，请关注响应中的错误码与提示信息。下表列出常见错误码及建议处理方式，便于您自助排查。
成功
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
响应判断
开放平台的业务成功和业务失败通常都返回 HTTP 200。调用方必须读取 JSON 响应中的 succeed 和 error_code，不能只根据 HTTP 状态判断业务是否成功。
JSON 响应使用以下字段，不使用 code / message 作为通用业务结果字段：
| 字段 | 说明 |
|---|---|
succeed | 业务是否成功；必须为 true 才能按成功结果处理 |
error_code | 业务错误码，0 表示成功 |
error_message | 错误提示，用于展示和排查；业务分支请使用错误码判断 |
data | 成功结果；失败时通常为 null |
例如，使用无效 X-API-Key 查询音色列表时，HTTP 状态码为 200，Content-Type 为 application/json，响应体为：
{
"error_code": 10003,
"error_message": "未授权",
"succeed": false,
"data": null
}
JavaScript 调用 JSON 接口时，先解析业务结果，再处理 HTTP 状态：
const response = await fetch("https://api.vuilabs.cn/v1/voice/list", {
headers: { "X-API-Key": "your-secret-key-here" },
});
const contentType = (response.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
if (contentType !== "application/json") {
throw new Error(`HTTP ${response.status}：未返回 JSON`);
}
const result = await response.json();
if (result.succeed !== true || result.error_code !== 0) {
throw new Error(`${result.error_code}: ${result.error_message}`);
}
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
console.log(result.data);
response.ok、Python 的 raise_for_status() 或 HTTP 200 只能判断 HTTP 层结果，不能代替上述业务判断。无效 Key、余额不足等业务失败不能当作成功，也不应盲目重试。
保存音色接口会使用 HTTP 401 等错误状态；上传接口的文件大小和频次超限分别返回 413、429。请求方法不匹配等协议层错误可能返回 405 等状态，且不一定使用统一 JSON 结构；具体以对应接口页为准。
音频生成成功时返回音频二进制，失败时返回 JSON。调用方须先检查 Content-Type，遇到 JSON 时读取业务错误，不能把 HTTP 200 的 JSON 错误体保存或播放为音频。参见音频生成接口。WebSocket 消息和 MCP JSON-RPC 使用各自协议中的错误字段，请参见对应接口说明。
通用错误
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 10000 | 请求处理失败 | 查看 error_message 中的具体原因；如提示繁忙或超时，可稍后重试，持续失败请联系支持 |
| 10001 | 参数错误 | 对照接口文档检查参数是否完整、类型是否正确 |
| 10002 | 资源不存在 | 确认所请求的资源是否存在、标识是否正确 |
| 10003 | 未授权 | 检查 API Key、Token 等凭证是否正确传入 |
| 10004 | 禁止访问 | 确认账号是否具备相应权限 |
| 10005 | 请求过于频繁 | 降低调用频率或稍后重试 |
| 10006 | 请求超时 | 检查网络环境后重试 |
| 10007 | Token 无效 | 检查 Token 是否正确 |
| 10008 | Token 已过期 | 重新获取或刷新 Token |
| 10009 | Token 不存在 | 重新登录或重新获取 Token |
| 10010 | 刷新 Token 失败 | 请重新登录 |
| 10011 | 密钥泄漏 | 请尽快在控制台作废相关密钥并更换新密钥 |
| 10012 | 已存在同名密钥 | 更换名称后重试 |
| 10013 | 请控制最多 500 字符 | 将内容控制在 500 字符以内 |
| 10014 | 连接数限制 | 降低并发连接数；必要时联系支持 |
| 10015 | 换个内容试试吧 | 修改内容后重试 |
| 10016 | 请控制最多 30 个密钥 | 删除不再使用的密钥后再创建 |
| 10017 | 个人音色数量已达上限 | 删除未使用项后再创建，或更换方案 |
| 10018 | 该名称已被占用，请换一个名称 | 更换名称后重试 |
| 10019 | 音色 ID 冲突，请重试 | 更换音色 ID 后重试 |
| 10020 | 音色已被 Agent 绑定 | 先解除 Agent 绑定后再删除 |
| 10021 | 音色正在处理中 | 稍后重试 |
账号相关
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 10101 | 用户不存在 | 确认账号是否已注册 |
| 10102 | 用户已存在 | 请使用登录流程，或更换注册信息 |
| 10103 | 用户已被禁用 | 联系支持 |
| 10104 | 邮箱已被注册 | 使用登录或更换邮箱 |
| 10105 | 手机号已被注册 | 使用登录或更换手机号 |
| 10106 | 请输入正确的邮箱 | 检查邮箱格式 |
| 10107 | 请输入正确格式的手机号 | 检查手机号格式 |
| 10108 | 密码格式错误 | 按页面提示调整密码规则 |
| 10109 | 密码错误 | 确认密码或使用找回功能 |
验证码相关
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 10120 | 您的验证码输入有误，请检查后重新输入 | 核对后重试，或重新获取验证码 |
| 10121 | 验证码已过期 | 重新获取验证码 |
| 10122 | 验证码已使用 | 重新获取验证码 |
| 10123 | 发送验证码过于频繁，请稍后再试 | 等待一段时间后重试 |
| 10124 | 发送验证码失败 | 稍后重试；确认手机或邮箱可用 |
| 10125 | 今日发送次数已达上限 | 次日再试或联系支持 |
| 10126 | 没有发短信记录 | 请先获取验证码后再校验 |
计费、短信/邮件与限额
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 20000 | 短信服务错误 | 稍后重试；持续失败请联系支持 |
| 20001 | 邮件服务错误 | 检查邮箱地址，稍后重试 |
| 20002 | 服务暂时不可用，请稍后再试 | 稍后重试；持续失败请联系支持 |
| 20003 | 余额不足 | 充值后再试 |
| 20004 | 最大金额为 1,000,000（一百万），请输入正确金额 | 将金额调整到允许范围内 |
音频文件与上传
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 20010 | 文件大小超过当前接口或上传场景限制 | 缩小文件后重试 |
| 20011 | object_key 和 url 必须提供其中一个 | 请求中请至少提供 object_key 或 url 之一 |
| 20012 | 音频文件格式错误，请重新上传正确的音频格式文件 | 使用支持的格式重新上传 |
| 20013 | 音频时长不足 1 秒，无法进行说话人分离 | 上传更长音频，或不使用该能力 |
| 20014 | 音频时长至少需要 2 秒，才能进行同步语音识别 | 上传至少 2 秒的音频 |
| 20015 | 克隆音色参考音频时长不能超过 60 秒 | 上传 3～60 秒的原始参考音频 |
| 20016 | 有效语音不足或未检测到可用语音 | 重新上传包含连续清晰语音的参考音频；以实际 error_message 为准 |
| 20017 | 音频停顿过长 | 音频内容不符合克隆要求，请重新录制连续说话的参考音频 |
实时会话类服务
若您使用实时会话类能力（如语音通话、同传等），可能遇到以下错误码：
| 错误码 | 说明 | 建议处理 |
|---|---|---|
| 40001 | 余额不足，无法开始会话 | 充值后再发起 |
| 40002 | 会话进行中，请先结束当前会话 | 结束当前会话后再开启新会话 |
| 40003 | 当前服务繁忙，请稍后再试 | 稍后重试 |