處理 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 原生 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)

將 Standard Integrity API 初始化時發生錯誤。

可能的解決方法

以指數輪詢方式重試。如果錯誤持續發生,請考慮提交錯誤。

另請參閱

如要瞭解傳統要求,請參閱 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) 與套件管理員中的 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)

提供的 Cloud 專案編號無效。

可能的解決方法

請使用已啟用 Play Integrity API 的 Cloud 專案所適用的 Cloud 專案編號。

另請參閱

如要瞭解傳統要求,請參閱 CLOUD_PROJECT_NUMBER_IS_INVALID

REQUEST_HASH_TOO_LONG (錯誤代碼 -17)

注意:只有在透過 StandardIntegrityErrorCode 使用標準要求時,才會回報此情況。

提供的 requestHash 過長。requestHash 長度不得超過 500 個半形字元。

可能的解決方法

請使用較短的 requestHash 重試。

INTEGRITY_TOKEN_PROVIDER_INVALID (錯誤代碼 -19)

注意:系統只會透過 StandardIntegrityErrorCode 回報標準要求。

StandardIntegrityTokenProvider 無效。此錯誤代碼僅適用於標準 API 要求,自程式庫 1.3.0 版起,適用於 Kotlin 和 Java 程式設計語言、適用於 Unity 1.3.0 以上版本的 Google Play Integrity 外掛程式,以及 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