處理 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 要求,自以下版本起開始支援:Kotlin 和 Java 程式設計語言庫 1.3.0 版本、適用於 Unity 的 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