处理 Play Integrity API 错误代码

如果应用使用 Play Integrity API 发出请求,但调用失败,系统会返回错误代码。返回的错误代码类型取决于请求类型。

重试策略

对于在后台发生且在用户会话期间不影响用户体验的 Play Integrity 操作,请使用指数退避。

例如,在确认新购买时,适合实施此策略,因为此操作可以在后台进行,并且如果发生错误,确认无需实时进行。

首次失败后,在重试前先等待 5 秒钟。

实施重试策略,将最大尝试次数作为退出条件,并每次以指数方式增加延迟(10 秒、20 秒)。

执行这些重试尝试时,检查网络连接,不要使设备过载。

如果在三次重试尝试后仍然出现错误,请将结果视为客户端未能通过所有完整性检查。错误可能有多种原因,包括(但不限于):设备过载、网络连接问题或攻击者尝试。

Java 库的错误代码值

IntegrityErrorCode StandardIntegrityErrorCode
-1 API_NOT_AVAILABLE API_NOT_AVAILABLE
-2 PLAY_STORE_NOT_FOUND PLAY_STORE_NOT_FOUND
-3 NETWORK_ERROR NETWORK_ERROR
-4 PLAY_STORE_ACCOUNT_NOT_FOUND
-5 APP_NOT_INSTALLED APP_NOT_INSTALLED
-6 PLAY_SERVICES_NOT_FOUND PLAY_SERVICES_NOT_FOUND
-7 APP_UID_MISMATCH APP_UID_MISMATCH
-8 TOO_MANY_REQUESTS TOO_MANY_REQUESTS
-9 CANNOT_BIND_TO_SERVICE CANNOT_BIND_TO_SERVICE
-10 NONCE_TOO_SHORT
-11 NONCE_TOO_LONG
-12 GOOGLE_SERVER_UNAVAILABLE GOOGLE_SERVER_UNAVAILABLE
-13 NONCE_IS_NOT_BASE64
-14 PLAY_STORE_VERSION_OUTDATED PLAY_STORE_VERSION_OUTDATED
-15 PLAY_SERVICES_VERSION_OUTDATED PLAY_SERVICES_VERSION_OUTDATED
-16 CLOUD_PROJECT_NUMBER_IS_INVALID CLOUD_PROJECT_NUMBER_IS_INVALID
-17 CLIENT_TRANSIENT_ERROR REQUEST_HASH_TOO_LONG
-18 CLIENT_TRANSIENT_ERROR
-19 INTEGRITY_TOKEN_PROVIDER_INVALID
-100 INTERNAL_ERROR INTERNAL_ERROR

原生库的其他错误代码值

IntegrityErrorCode StandardIntegrityErrorCode
-100 INTEGRITY_INTERNAL_ERROR STANDARD_INTEGRITY_INTERNAL_ERROR
-101 INTEGRITY_INITIALIZATION_NEEDED STANDARD_INTEGRITY_INITIALIZATION_NEEDED
-102 INTEGRITY_INITIALIZATION_FAILED STANDARD_INTEGRITY_INITIALIZATION_FAILED
-103 INTEGRITY_INVALID_ARGUMENT STANDARD_INTEGRITY_INVALID_ARGUMENT

可重试的错误代码

这些错误有时是由于暂时性情况引起的,因此您应该重试调用。

NETWORK_ERROR(错误代码 -3)

此错误表示设备与 Play 系统之间的网络连接存在问题。

可能的解决方案

要恢复,请让用户检查网络连接,并根据触发错误的操作使用简单的重试或指数退避。

另请参阅

针对经典请求的 NETWORK_ERROR

TOO_MANY_REQUESTS(错误代码 -8)

调用应用对 API 发送了太多请求,已被限制。

可能的解决方案

  1. 请求提高每日最大请求次数
  2. 使用指数退避进行重试。

另请参阅

针对经典请求的 TOO_MANY_REQUESTS

GOOGLE_SERVER_UNAVAILABLE(错误代码 -12)

未知内部 Google 服务器错误。

可能的解决方案

使用指数退避进行重试。如果持续失败,请考虑提交 bug

另请参阅

针对经典请求的 GOOGLE_SERVER_UNAVAILABLE

CLIENT_TRANSIENT_ERROR(错误代码 -18)

客户端设备上发生了暂时性错误。

对于 Standard API 请求,此错误自以下版本开始支持:Kotlin 和 Java 的 Play Integrity API 库版本 1.3.0;适用于 Unity 的 Google Play Integrity 插件版本 1.3.0 或更高版本;以及 Play Core 原生 SDK 版本 1.13.0 或更高版本。

可能的解决方案

使用指数退避进行重试。

另请参阅

针对经典请求的 CLIENT_TRANSIENT_ERROR

注意:使用 Classic API 请求时报告此错误,返回的值为 -17。

INTERNAL_ERROR(错误代码 -100)

未知内部错误。

可能的解决方案

使用指数退避进行重试。如果持续失败,请考虑提交 bug。

另请参阅

针对经典请求的 INTERNAL_ERROR

STANDARD_INTEGRITY_INTERNAL_ERROR(错误代码 -100)

未知内部错误。

可能的解决方案

使用指数退避进行重试。如果持续失败,请考虑提交 bug。

另请参阅

请参阅针对经典请求的 INTEGRITY_INTERNAL_ERROR

STANDARD_INTEGRITY_INITIALIZATION_FAILED(错误代码 -102)

初始化 Standard Integrity API 时出错。

可能的解决方案

使用指数退避进行重试。如果持续失败,请考虑提交 bug。

另请参阅

请参阅针对经典请求的 INTEGRITY_INITIALIZATION_FAILED

不可重试的错误代码

在此类情况下,自动重试不太可能有帮助。但是,如果用户解决了导致问题的情况,手动重试可能会有帮助。例如,如果用户将 Play 商店版本更新到支持的版本,则手动重试初始操作可能奏效。

API_NOT_AVAILABLE(错误代码 -1)

设备上安装的 Play 商店版本可能太旧,且 Integrity API 不可用。另一种可能性是未在 Google Play 管理中心启用 Integrity API。

可能的解决方案

  • 确保已在 Google Play 管理中心启用 Integrity API。
  • 请用户更新 Play 商店。

另请参阅

请参阅针对经典请求的 API_NOT_AVAILABLE

PLAY_STORE_NOT_FOUND(错误代码 -2)

设备上未找到官方 Play 商店应用。

可能的解决方案

请用户安装或启用 Google Play 商店。

另请参阅

请参阅针对经典请求的 PLAY_STORE_NOT_FOUND

PLAY_STORE_ACCOUNT_NOT_FOUND(错误代码 -4)

注意:此错误仅通过 IntegrityErrorCode 针对经典请求报告。

设备上未找到 Play 商店账号。请注意,Play Integrity API 现在支持未经验证的请求。此错误代码仅用于缺少支持的旧版 Play 商店。

可能的解决方案

请用户更新并登录 Google Play 商店。

APP_NOT_INSTALLED(错误代码 -5)

调用应用未安装。可能存在问题(可能是攻击)。

可能的解决方案

不可操作。将结果视为客户端未能通过所有完整性检查。

另请参阅

请参阅针对经典请求的 APP_NOT_INSTALLED

PLAY_SERVICES_NOT_FOUND(错误代码 -6)

Play 服务不可用或需要更新。

可能的解决方案

请用户安装、更新或启用 Play 服务。

另请参阅

请参阅针对经典请求的 APP_NOT_INSTALLED

APP_UID_MISMATCH(错误代码 -7)

调用应用的 UID(用户 ID)与软件包管理器中的不匹配。

可能的解决方案

不可操作。将结果视为客户端未能通过所有完整性检查。

另请参阅

请参阅针对经典请求的 APP_UID_MISMATCH

CANNOT_BIND_TO_SERVICE(错误代码 -9)

绑定到 Play 商店中的服务失败。可能是因为设备上安装的 Play 商店版本太旧。

可能的解决方案

请用户更新 Google Play 商店。

另请参阅

请参阅针对经典请求的 CANNOT_BIND_TO_SERVICE

NONCE_TOO_SHORT(错误代码 -10)

注意:此错误仅通过 IntegrityErrorCode 针对经典请求报告。

Nonce 长度太短。base64 编码前,nonce 必须至少有 16 字节。

可能的解决方案

使用更长的 nonce 重试。

NONCE_TOO_LONG(错误代码 -11)

注意:此错误仅通过 IntegrityErrorCode 针对经典请求报告。

Nonce 长度太长。base64 编码前,nonce 必须小于 500 字节。

可能的解决方案

使用更短的 nonce 重试。

NONCE_IS_NOT_BASE64(错误代码 -13)

注意:此错误仅通过 IntegrityErrorCode 针对经典请求报告。

Nonce 未编码为 base64 网络安全无换行字符串。

可能的解决方案

使用正确格式的 nonce 重试。

PLAY_STORE_VERSION_OUTDATED(错误代码 -14)

Google Play 商店应用需要更新。

可能的解决方案

请用户更新 Google Play 商店。

另请参阅

请参阅针对经典请求的 PLAY_STORE_VERSION_OUTDATED

PLAY_SERVICES_VERSION_OUTDATED(错误代码 -15)

Google Play 服务需要更新。

可能的解决方案

请用户更新 Google Play 服务。

另请参阅

请参阅针对经典请求的 PLAY_SERVICES_VERSION_OUTDATED

CLOUD_PROJECT_NUMBER_IS_INVALID(错误代码 -16)

提供的云项目编号无效。

可能的解决方案

请使用您已启用 Play Integrity API 的云项目的云项目编号。

另请参阅

请参阅针对经典请求的 CLOUD_PROJECT_NUMBER_IS_INVALID

REQUEST_HASH_TOO_LONG(错误代码 -17)

注意:此错误仅通过 StandardIntegrityErrorCode 使用标准请求时报告。

提供的 requestHash 太长。requestHash 长度必须小于 500 个字符。

可能的解决方案

使用更短的 requestHash 重试。

INTEGRITY_TOKEN_PROVIDER_INVALID(错误代码 -19)

注意:此错误仅通过 StandardIntegrityErrorCode 针对标准请求报告。

StandardIntegrityTokenProvider 无效。此错误代码仅适用于 Standard API 请求,从 Kotlin 和 Java 编程语言的库版本 1.3.0、适用于 Unity 的 Google Play Integrity 插件 1.3.0 或更高版本以及 Play Core Native SDK 1.13.0 或更高版本开始支持。

可能的解决方案

请求新的完整性令牌提供程序。

STANDARD_INTEGRITY_INITIALIZATION_NEEDED(错误代码 -101)

StandardIntegrityManager 未初始化。

可能的解决方案

请先调用 StandardIntegrityManager_init()

另请参阅

请参阅针对经典请求的 INTEGRITY_INITIALIZATION_NEEDED

STANDARD_INTEGRITY_INVALID_ARGUMENT(错误代码 -103)

传递给 Standard Integrity API 的参数无效。

可能的解决方案

使用正确的参数重试。

另请参阅

请参阅针对经典请求的 INTEGRITY_INVALID_ARGUMENT