处理 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 服务器内部错误。

可能的解决方案

使用指数退避重试。如果持续失败,请考虑提交错误报告

另请参阅

对于经典请求,出现GOOGLE_SERVER_UNAVAILABLE

CLIENT_TRANSIENT_ERROR(错误代码 -18)

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

对于标准 API 请求,此功能自 Kotlin 和 Java 版Play Integrity API 库 1.3.0 版、Unity 版 Google Play Integrity 插件 1.3.0 或更高版本以及Play Core Native SDK 1.13.0 或更高版本起受支持。

可能的解决方案

使用指数退避重试。

另请参阅

对于经典请求,出现CLIENT_TRANSIENT_ERROR

注意:使用经典 API 请求时,返回的值为 -17。

INTERNAL_ERROR(错误代码 -100)

未知的内部错误。

可能的解决方案

使用指数退避重试。如果持续失败,请考虑提交错误报告。

另请参阅

对于经典请求,出现INTERNAL_ERROR

STANDARD_INTEGRITY_INTERNAL_ERROR(错误代码 -100)

未知的内部错误。

可能的解决方案

使用指数退避重试。如果持续失败,请考虑提交错误报告。

另请参阅

请参阅经典请求的INTEGRITY_INTERNAL_ERROR

STANDARD_INTEGRITY_INITIALIZATION_FAILED(错误代码 -102)

初始化标准完整性 API 时出错。

可能的解决方案

使用指数退避重试。如果持续失败,请考虑提交错误报告。

另请参阅

请参阅经典请求的INTEGRITY_INITIALIZATION_FAILED

不可重试的错误代码

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

API_NOT_AVAILABLE(错误代码 -1)

设备上安装的 Play 商店版本可能较旧,并且完整性 API 不可用。另一种可能是完整性 API 在 Google Play Console 中未启用。

可能的解决方案

  • 确保在 Google Play Console 中启用了完整性 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)与包管理器中的 UID 不匹配。

可能的解决方案

无法操作。将结果视为客户端已失败所有完整性检查。

另请参阅

请参阅经典请求的APP_UID_MISMATCH

CANNOT_BIND_TO_SERVICE(错误代码 -9)

绑定到 Play 商店中的服务失败。这可能是由于设备上安装了旧版 Play 商店造成的。

可能的解决方案

请用户更新 Google Play 商店。

另请参阅

请参阅经典请求的CANNOT_BIND_TO_SERVICE

NONCE_TOO_SHORT(错误代码 -10)

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

Nonce 长度过短。Nonce 在 base64 编码之前必须至少为 16 个字节。

可能的解决方案

使用更长的 Nonce 重试。

NONCE_TOO_LONG(错误代码 -11)

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

Nonce 长度过长。Nonce 在 base64 编码之前必须小于 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无效。此错误代码仅适用于标准 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)

传递给标准完整性 API 的参数无效。

可能的解决方案

使用正确的参数重试。

另请参阅

请参阅经典请求的INTEGRITY_INVALID_ARGUMENT