目录

用户认证错误码

本文档介绍用户认证服务特有的错误码。帮助开发者定位和处理认证相关的异常情况。

以下仅介绍本模块特有错误码，通用错误码请参考通用错误码说明文档。

12500001 认证不通过

错误信息

Authentication failed.

错误描述

用户身份认证不通过，表示用户提供的认证凭据与设备中已注册的凭据比对不匹配。常见的认证结果，通常表示用户输入错误或使用了未注册的凭据。

可能原因

  1. 用户输入的密码、人脸或指纹与已注册的凭据不匹配。
  2. 用户使用了未注册的认证凭据尝试认证。
  3. 生物特征采集质量不佳，导致比对失败（如人脸光线不足、指纹按压不完整等）。

处理步骤

  1. 建议提示用户重新尝试认证。
  2. 对于生物认证失败，可提示用户调整操作方式（如改善光线环境、正确按压指纹传感器）。
  3. 如果多次失败，建议用户检查是否已注册相应凭据，或切换到其他认证方式。
  4. 记录失败次数，当达到阈值时提示用户可能触发锁定机制。

12500002 身份认证系统通用错误码

错误信息

General operation error.

错误描述

身份认证系统发生无法恢复的内部错误。通用错误码，表示系统内部工作异常，开发者无法通过调整参数或操作方式来解决。

可能原因

  1. NAPI层解析参数出错，参数传递过程中发生异常。
  2. 用户认证服务的进程没有启动或意外终止。
  3. IPC通信的proxy客户端写数据出错，数据传输异常。
  4. IPC通信的stub服务端解析数据出错，数据接收异常。
  5. 获取driver服务出错，底层驱动服务不可用。
  6. 系统资源不足，内存分配失败。

处理步骤

  1. 系统服务内部工作异常，建议重新调用接口。
  2. 如果多次重试仍然失败，建议重启设备尝试。

12500003 认证被取消

错误信息

Authentication canceled.

错误描述

认证操作被取消，表示用户主动或被动终止了认证过程。

可能原因

  1. 用户手动点击取消按钮或返回键，主动取消认证。
  2. 应用调用cancel接口主动取消认证。
  3. 后续发起的认证请求优先完成，致使前置认证请求被强制取消。

处理步骤

  1. 根据用户意图决定是否重新发起认证。
  2. 如果是系统抢占取消，建议稍后重新发起认证请求。
  3. 避免同时发起多个认证请求，防止相互抢占。

12500004 认证操作超时

错误信息

Authentication timeout.

错误描述

认证操作超过设定的时限。用户在规定时间内未完成认证交互，系统自动终止认证过程。

可能原因

  1. 用户在认证界面停留过久，未及时输入密码或进行生物认证操作。
  2. 人脸认证时用户未正视摄像头，导致长时间无法采集有效人脸图像。

处理步骤

  1. 建议用户重新发起认证，并注意操作时限。
  2. 提示用户在认证时及时响应，如人脸认证时正视摄像头。
  3. 对于密码认证，提醒用户在超时前完成密码输入。

12500005 认证类型不支持

错误信息

The authentication type is not supported.

错误描述

表示当前设备或系统不支持请求的认证方式。

可能原因

  1. 传入的认证类型参数无效，例如调用getAvailableStatus接口时传入的authType参数不在支持的范围内（PIN、FACE、FINGERPRINT等）。
  2. 传入的认证类型参数在本设备上不支持，例如在没有部署指纹传感器的设备上发起指纹认证。

处理步骤

  1. 请检查传入的认证类型参数是否正确，确保参数值在支持的范围内。
  2. 发起认证之前，调用getAvailableStatus预先检查设备是否支持指定的认证类型，如果设备不支持某种认证类型，建议切换到其他支持的认证类型。

12500006 认证信任等级不支持

错误信息

The authentication trust level is not supported.

错误描述

表示当前认证类型无法达到请求的安全等级。

可能原因

  1. 调用getAvailableStatus或getUserAuthInstance接口时，传入的authTrustLevel参数不在有效范围内（应为ATL1(10000)、ATL2(20000)、ATL3(30000)或ATL4(40000)）。
  2. 当前设备的认证能力无法达到指定的认证信任等级，例如在2D人脸认证设备上发起ATL4等级的人脸认证。
  3. 用户注册的凭据安全等级低于请求的认证信任等级，如4位PIN密码只能达到ATL3，无法满足ATL4要求。

处理步骤

  1. 检查传入的authTrustLevel参数是否在有效范围内（ATL1-ATL4）。
  2. 如果参数在有效范围内，则可能是当前设备不支持该认证信任等级，建议应用降低认证等级。
  3. 调用getAvailableStatus接口预先检查设备是否支持指定的认证信任等级。
  4. 如果业务需要高安全等级，可考虑使用支持更高等级的认证类型（如使用PIN代替人脸认证）。
  5. 参见认证可信等级划分原则了解各认证类型支持的等级范围。

12500007 认证服务繁忙

错误信息

Authentication service is busy.

错误描述

认证服务正忙于处理其他请求，无法响应当前的认证请求。表示系统认证服务暂时不可用。

可能原因

  1. 认证服务正在处理其他应用的认证请求，资源被占用。
  2. 系统正在进行其他认证相关操作（如设备解锁），无法响应新的认证请求。
  3. 认证服务启动过程中暂时无法响应请求。

处理步骤

  1. 如果是服务繁忙，建议稍后重新发起认证请求。
  2. 避免在短时间内频繁发起认证请求，可增加请求间隔时间。

12500008 参数校验失败

错误信息

The parameter is out of range.

错误描述

参数取值超出合法范围，表示传入的参数值不符合接口定义的有效范围。

可能原因

  1. 参数值超出定义的有效范围，如reuseDuration超过MAX_ALLOWABLE_REUSE_DURATION（300000毫秒）。
  2. 数值类型参数为负数或零，但接口要求为正整数。
  3. 字符串参数长度超过限制，如title超过500字符、navigationButtonText超过60字符。
  4. 数组参数为空但接口要求非空，如authType列表为空。
  5. Uint8Array参数长度超过限制，如challenge超过32字节、authToken超过1024字节。

处理步骤

  1. 参考接口文档中的参数说明，确认各参数的有效取值范围，修正参数后重新发起请求。
  2. 对于数值参数，确保在有效范围内且符合类型要求。
  3. 对于字符串参数，确保长度不超过限制且内容符合要求。
  4. 对于数组参数，确保不为空且元素有效。
  5. 对于二进制数据参数，确保长度在有效范围内。

12500009 认证被锁定

错误信息

Authentication is locked out.

错误描述

指定认证方式已被锁定，表示因连续多次认证失败触发防暴力保护机制，认证功能暂时不可用。

可能原因

用户频繁尝试错误的认证凭据，系统启动保护机制防止暴力破解。

处理步骤

  1. 提示用户认证已锁定，需等待锁定解除后才能继续认证。
  2. 可通过getAuthLockState接口查询当前锁定状态，包括剩余锁定时间和剩余尝试次数。
  3. 如果是临时锁定，提示用户等待锁定时间到期后重新尝试。
  4. 如果是永久锁定，提示用户使用密码解锁后才能继续使用生物认证。
  5. 建议用户在锁定解除后使用正确的凭据进行认证，避免再次触发锁定。

12500010 该类型的凭据没有录入

错误信息

The type of credential has not been enrolled.

错误描述

用户未录入指定类型的认证凭据，表示设备中没有注册请求的认证方式对应的凭据数据。

可能原因

  1. 调用userAuth模块的getAvailableStatus接口检查认证能力时，传入的authType参数为FACE或FINGERPRINT，但用户未在设备上录入人脸或指纹凭据。
  2. 调用start接口发起认证时，请求的认证类型对应的凭据未录入，如发起指纹认证但用户未录入指纹。
  3. 用户曾录入的凭据已被删除，如用户在设置中删除了已注册的人脸或指纹。
  4. 新用户账号未录入任何认证凭据。

处理步骤

  1. 检查用户是否已录入该类型的认证凭据。
  2. 如果用户未录入，引导用户前往系统设置录入相应凭据（人脸、指纹或PIN）。
  3. 可通过getEnrolledState接口查询凭据注册状态。
  4. 如果用户拒绝录入，建议切换到其他已录入的认证类型。
  5. 提示用户录入凭据后才能使用相应的认证功能。

12500011 提示/通知切换自定义认证

错误信息

Switched to the custom authentication process.

错误描述

用户取消系统认证方式，选择使用应用自定义认证。

可能原因

用户在身份认证控件界面点击了导航按钮（由navigationButtonText参数指定），当前的系统认证操作被用户取消，选择使用应用自定义认证方式。

处理步骤

应用收到此错误码后，需拉起自定义认证界面供用户完成认证。

12500013 密码过期

错误信息

Operation failed because of PIN expired.

错误描述

密码过期，表示密码因安全策略要求已过期。

可能原因

  1. 系统锁屏口令已过期，通常由企业安全策略或系统设置导致（如要求定期更新密码）。
  2. 用户发起密码认证、指纹认证或人脸认证时，系统检测到锁屏密码已过期。
  3. 密码过期后，生物认证（指纹、人脸）也无法使用，因为它们依赖密码作为备用解锁方式。

处理步骤

  1. 提示用户密码已过期，需更新密码后才能继续使用认证功能。
  2. 引导用户前往系统设置更新密码。
  3. 用户更新密码后，可重新发起认证请求。
  4. 如果是企业环境，可能需要联系管理员了解密码更新要求。
  5. 提醒用户定期更新密码以避免过期影响使用。