处理 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 一直失败,请考虑提交 bug

另请参阅

GOOGLE_SERVER_UNAVAILABLE(适用于传统请求)。

CLIENT_TRANSIENT_ERROR(错误代码 -18)

客户端设备上出现暂时性错误。

对于标准 API 请求,从以下版本的 Kotlin 和 Java 版 Play Integrity API 库Google Play Integrity Plugin for Unity 1.3.0 或更高版本以及 Play Core 原生 SDK 1.13.0 或更高版本开始支持此功能。

可能的解决方案

使用指数退避算法重试。

另请参阅

CLIENT_TRANSIENT_ERROR(适用于传统请求)。

注意:在使用传统 API 请求时进行报告时,返回值为 -17。

INTERNAL_ERROR(错误代码 -100)

未知内部错误。

可能的解决方案

使用指数退避算法重试。 如果 bug 一直失败,请考虑提交 bug。

另请参阅

INTERNAL_ERROR(适用于传统请求)。

STANDARD_INTEGRITY_INTERNAL_ERROR(错误代码 -100)

未知内部错误。

可能的解决方案

使用指数退避算法重试。 如果 bug 一直失败,请考虑提交 bug。

另请参阅

对于传统请求,请参阅 INTEGRITY_INTERNAL_ERROR

STANDARD_INTEGRITY_INITIALIZATION_FAILED(错误代码 -102)

初始化 Standard Integrity API 时出错。

可能的解决方案

使用指数退避算法重试。 如果 bug 一直失败,请考虑提交 bug。

另请参阅

对于传统请求,请参阅 INTEGRITY_INITIALIZATION_FAILED

不可重试的错误代码

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

API_NOT_AVAILABLE(错误代码 -1)

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

可能的解决方案

  • 确保已在 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)与软件包管理器中的 UID 不符。

可能的解决方案

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

另请参阅

对于传统请求,请参阅 APP_UID_MISMATCH

CANNOT_BIND_TO_SERVICE(错误代码 -9)

未能绑定到 Play 商店中的服务。这可能是因为在设备上安装的 Play 商店版本太低。

可能的解决方案

让用户更新 Google Play 商店。

另请参阅

对于传统请求,请参阅 CANNOT_BIND_TO_SERVICE

NONCE_TOO_SHORT(错误代码 -10)

注意:系统仅会针对通过 IntegrityErrorCode 发送的传统请求报告这个问题。

Nonce 长度太短。Nonce 的长度必须至少为 16 字节(在 base64 编码之前)。

可能的解决方案

使用更长的 Nonce 重试。

NONCE_TOO_LONG(错误代码 -11)

注意:系统仅会针对通过 IntegrityErrorCode 发送的传统请求报告这个问题。

Nonce 长度太长。Nonce 的长度必须小于 500 字节(在 base64 编码之前)。

可能的解决方案

使用更短的 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 项目的编号。

另请参阅

对于传统请求,请参阅 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、Google Play Integrity Plugin for Unity 1.3.0 或更高版本以及 Play Core 原生 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