从调用失败到成功返回：人脸核身全链路排查指南

摘要：

人脸核身调用失败往往卡在某个具体环节。本文按"客户端 → 网络与签名 → 服务端 → 设备环境"四层拆解，每层给出可对照的错误码与处理动作，帮你快速定位问题究竟出在哪一步。

一、先定位问题在哪一层

排查的第一步不是改代码，而是判断问题发生在哪一层。按下面的顺序收集信息，可以快速缩小范围：

1. 客户端能否正常发起核身（SDK 是否初始化成功、页面是否黑屏）
2. 网络与签名是否通过（请求是否到达服务端、签名是否验签通过）
3. 服务端接口返回什么错误（后台返回码 / API 错误码）
4. 用户与环境在核身过程中看到什么提示（摄像头、光线、遮挡）

把这四类信息收集齐，问题范围基本就清楚了一半。下面逐层给出常见现象、定位方法与处理动作。

二、客户端层：SDK 初始化与编译

这一层的失败几乎都发生在"核身还没真正开始"之前，典型现象是 SDK 初始化失败、页面黑屏或编译报错。

提示：iOS 若提示 Class not found，通常是 SDK 未正确链接或 framework 未设为 Embed & Sign，需在 Xcode 的 Build Phases 中确认。

三、网络与签名层

签名验签失败是这一层最高频的问题，本质是客户端生成的 sign 与服务端用相同密钥和算法重算的结果不一致，与人脸识别算法本身无关。腾讯云采用标准 HMAC-SHA256（大文件场景为 TC3-HMAC-SHA256）签名方案：

sign = Base64( HmacSHA256(key = AppSecret, data = canonicalString) )

其中 canonicalString 必须严格满足：

1. 所有参与签名的参数按字段名字典序升序排列；
2. 每个键值对经 UTF-8 编码后执行 RFC 3986 兼容的 URL Encode（注意空格编码为 %20 而非 +）；
3. 键值间用 = 连接，参数间用 & 拼接；
4. AppId、Timestamp、Nonce 为强制字段，缺一不可。

对照下表逐项排查：

建议：优先用官方 SDK 调用，SDK 内含签名生成逻辑，可避免自行组装复杂签名导致的各类错误。子账号调用还需确认 CAM 策略已授予慧眼相关操作权限。

四、服务端层：后台返回码

服务端调用成功后，仍可能返回业务错误码。以下基于腾讯云慧眼官方错误码整理，按类别对照：

系统返回码

活体检测返回码

证件图像比对返回码

说明：返回码是否计费与业务是否开通相关，完整清单以官方错误码文档为准。API 侧公共错误码（如 InvalidParameterValue.BizTokenIllegal、UnauthorizedOperation.Nonactivated）表示 BizToken 非法或服务未开通，需先到控制台开通服务并核对 BizToken。

五、设备与环境层

很多"看起来是代码问题"的失败，其实来自设备环境。这类问题需要在交互上给出明确提示，而不是笼统报错：

• 摄像头被占用：其他应用（如视频通话）占用了摄像头，关闭后重试。
• 摄像头权限被拒绝：引导用户到系统设置重新授权。
• 光线过暗或逆光：对应返回码 1202，提示在光源充足的室内环境验证。
• 面部被遮挡：口罩、帽子、墨镜会导致活体检测不通过，提示移除遮挡物。
• 浏览器不支持：H5 场景下部分浏览器不支持实时检测模式，建议更换浏览器或使用备用方案。
• 设备风险（Plus 版）：GetFaceIdResult 可返回设备风险标签，如 01 Root/越狱、03 模拟器、05 摄像头被劫持等，命中时结合业务风控处置。

六、排查流程总结

碰到调用失败时，按这个顺序走：

1. 分层定位：先收集客户端提示、接口返回码和用户环境三类信息，判断问题落在哪一层；
2. 逐项排除：对照上表在该层内定位具体错误码，执行对应处理动作；
3. 闭环兜底：确认失败路径有明确的用户提示和重试入口，避免用户卡死在错误页。

如果按上述方式仍无法定位，保留完整的调用日志（含 RequestId、错误码、请求时间与参数），联系官方技术支持协助排查。

排查过程中如需查阅最新错误码与接入文档，可参考腾讯云慧眼人脸核身的官方文档。当前慧眼产品正在开展限时特惠活动，低至 3.3 折，详情见活动页面。