必须从返回码切入排查非预期结果：先查控制台日志中Response Body的code字段，区分HTTP状态码（未达业务层）、SDK正数错误码（本地问题）与API负数错误码（服务端拒绝），再按-1001、-2003、-3002三类高频码对照文档定位。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在百度一镜数字人控制台调用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错误码，代表请求已抵达服务端并被明确拒绝或处理失败。这类错误必须对照官方错误码文档逐条比对。
调用百度PaddleOCR‑VL大模型API，支持PDF、Word、PPT、图片等多格式文档解析，精准识别印刷体、手写体、表格、公式、图表、印章等复杂元素，支持100+语言，可处理不规则布局和跨页长文档。触发词：文档解析、VLM解析、大模型OCR、PaddleOCR、多模态文档、手写识别、公式识别、复杂版面。
【-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()处理。
