处理 Play Integrity API 错误代码

如果您的应用发出 Play Integrity API 请求,但调用失败,则您的应用会收到一个错误代码。这些错误可能是由多种原因造成的,例如环境问题(如网络连接不佳)、API 集成问题,或恶意活动和主动攻击。所返回错误代码的类型取决于请求的类型:

重试策略

对于在后台发生的 Play Integrity 操作,请使用指数退避算法,该算法在用户进行会话时不影响用户体验。

例如,在确认新购买交易时可以实现此算法,因为此操作可以在后台进行,如果出现错误,则不需要实时进行确认。

第一次失败后,先延迟 5 秒钟,然后再重试。

实现一种重试策略,将尝试次数上限作为退出条件,每次都以指数方式增加延迟时间(10 秒、20 秒)。

执行这些重试操作时,请检查网络连接,并避免设备过载。

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

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 系统之间的网络连接出现问题。

可能的解决方案

  1. 使用 GET_INTEGRITYGET_STRONG_INTEGRITY 对话框启动 Play 指导式体验,帮助用户建立并确认网络连接。
  2. 让用户检查网络连接,并使用基本重试策略或指数退避算法,具体取决于哪个操作触发了错误。

另请参阅

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)

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

对于标准 API 请求,此错误代码从以下版本开始受支持:适用于 Kotlin 和 Java 的 Play Integrity API 库 1.3.0 版、Google Play Integrity Plugin for Unity 1.3.0 或更高版本以及 Play Core 原生 SDK 1.13.0 或更高版本。

可能的解决方案

使用指数退避算法重试。

另请参阅

CLIENT_TRANSIENT_ERROR:用于传统请求。

注意:如果在发出经典版 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。