遇到非预期结果——例如视频生成失败、直播推流中断或状态无响应时，建议不要仅依赖前端提示或盲目重试。正确的排查思路是：从返回码入手。打开控制台日志，找到 Response Body 中的 code 字段，判断它是 HTTP 状态码（说明请求未到达业务层）、SDK 正数错误码（本地问题）还是 API 负数错误码（服务端明确拒绝）。然后针对 -1001、-2003、-3002 这三类高频错误码，对照官方文档逐一排查。

回到正题，在百度一镜数字人控制台调用 API 后，若返回了非预期结果——视频生成失败、直播推流中断、状态无响应——请务必第一时间从返回码切入，不要依赖前端界面提示或简单重试。

确认返回码是否来自百度一镜数字人服务

第一步：进入控制台「日志查询」页面，选择对应应用和时间范围，点击某条失败请求的「详情」，找到 Response Body 中的 code 字段。

注意：该 code 必须是百度一镜数字人官方文档定义的错误码（如 -1001、20003），而非 HTTP 状态码（如 400、500）。如果看到的是 HTTP 状态码，说明请求根本未到达业务层，问题出在网络或网关配置上。

区分 SDK 错误码与 API 错误码

方法一：查询 SDK 初始化阶段错误码
如果日志中 code 为正数（如 10000、10007），属于 SDK 内部状态码，表示 SDK 已加载成功但尚未发起真实 API 请求。此时需检查本地资源路径、人脸鉴权文件是否存在、网络连通性是否正常。

方法二：查询 API 调用阶段错误码
如果 code 为负数（如 -2001、-3005），属于百度一镜数字人服务端返回的 API 错误码，代表请求已抵达服务端并被明确拒绝或处理失败。这类错误必须对照官方错误码文档逐条比对。

【-2001 表示视频生成参数非法，常见于 duration 字段超限或 format 不支持】

快速定位三类高频错误码

第一步：遇到 code: -1001 → 检查 Access Token 是否过期或无效。该错误码出现时，message 字段通常为 “invalid access_token”，需立即重新调用 /oauth/2.0/token 接口获取新 token。

第二步：遇到 code: -2003 → 查看 message 中是否含 “quota exceeded”。若是，说明当前 APP 的调用配额已耗尽，需登录控制台升级套餐或等待次日重置。

第三步：遇到 code: -3002 → 检查请求体中 video_id 或 stream_id 是否为空或格式错误。该 ID 必须为 16 位十六进制字符串（如 a1b2c3d4e5f67890），少一位或多一位都会触发此错误。

这一步操作很简单，直接复制日志里的 ID 粘贴到正则校验工具验证即可。

排除 JSON 解析导致的假错误码

打开日志原始响应内容，确认 Response Body 是否为合法 JSON。若开头是 %7B%22code%22%3A-2001... 这类 URL 编码字符，说明前端未正确解码响应，实际错误码被包裹在编码字符串里，需先调用 decodeURIComponent() 再解析 JSON。

Python 开发者容易忽略这点：用 requests.get().text 直接读取会得到原始编码字符串，必须用 .json() 方法或手动 urllib.parse.unquote() 处理。