處理 eUICC API 錯誤

eUICC API 會提供錯誤代碼，協助應用程式和使用者排解下載、啟用、停用和刪除 eSIM 設定檔的問題。

處理錯誤

在呼叫 eUICC API 時發生錯誤時，系統會提供待處理意圖回呼，並使用 EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE 做為取得詳細錯誤代碼的索引鍵。自 Android 11 起，下列四個鍵和值會納入產生的意圖：

這四個值可讓 eUICC API 的呼叫端個別處理特定錯誤。以下範例說明如何處理這些錯誤。

int operationCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE)
int errorCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE)
String smdxSubjectCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE)
String smdxReasonCode = intent.get(EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE)

if (operationCode == OPERATION_DOWNLOAD && errorCode == ERROR_CARRIER_LOCKED) {
  // handle specific error i.e. tries to download but the device is carrier locked
} else if (operationCode == OPERATION_SMDX) {
  // handle all SM-DP+/SM-DS errors
} else if (errorCode == ERROR_TIME_OUT) {
  // handle all types of time out issues, regardless of operation.
} else if ("8.1".equals(smdxSubjectCode) && "3.1".equals(smdxReasonCode)) {
  // handle specific subject code and reason code: 8.1 and 4.1 means insufficient memory.
}

支援的作業和錯誤代碼組合

下表說明當地設定檔輔助程式 (LPA) 傳回的作業和錯誤代碼支援的組合。

作業和錯誤代碼組合
作業代碼 錯誤代碼 說明
OPERATION_SYSTEM 不適用 發生內部錯誤，例如，執行緒遭到中斷，或發生 IOException 錯誤。
OPERATION_SIM_SLOT 不適用 執行 SIM 卡插槽作業時發生內部錯誤。
ERROR_TIME_OUT 嘗試執行 SIM 卡插槽作業時逾時。
ERROR_EUICC_MISSING 裝置上沒有可用的 eUICC 或已啟用的 eUICC。
OPERATION_EUICC_CARD 不適用 執行 eUICC 作業時發生內部錯誤。
ERROR_UNSUPPORTED_VERSION eUICC (晶片) 版本和 EuiccCard (軟體) 版本不相容。
ERROR_EUICC_MISSING 裝置中沒有 SIM 卡。例如，LPA 無法偵測 SIM 卡。
OPERATION_SMDX 不適用 執行 SM-DP+/SM-DS 作業時發生內部錯誤。
ERROR_ADDRESS_MISSING 沒有 SM-DP+ 位址可下載設定檔。
ERROR_INVALID_CONFIRMATION_CODE 剖析啟用碼時發生錯誤 (格式無效)。
ERROR_CERTIFICATE_ERROR 在 TLS 連線中用於驗證時，金鑰庫或憑證發生錯誤。
ERROR_NO_PROFILES_AVAILABLE SM-DP+ 沒有可用的設定檔。
ERROR_CONNECTION_ERROR 無法建立與伺服器的連線。
ERROR_INVALID_RESPONSE SM-DP+/SM-DS 伺服器傳回的回應無效。
OPERATION_SWITCH 不適用 執行切換作業時發生內部錯誤。
ERROR_CARRIER_LOCKED 裝置已鎖定 (SIM 卡已鎖定)，因此無法切換設定檔。
OPERATION_DOWNLOAD 不適用 執行下載作業時發生內部錯誤。
ERROR_DISALLOWED_BY_PPR eUICC 上的規則授權表為空值，或是設定檔政策規則不允許下載。
ERROR_INVALID_ACTIVATION_CODE 剖析啟用碼時發生錯誤 (格式無效)，或嘗試在沒有啟用碼的情況下下載。
ERROR_CARRIER_LOCKED 裝置已鎖定 (SIM 卡已鎖定)，因此無法下載。
ERROR_INCOMPATIBLE_CARRIER 電信業者在黑名單中，LPA 無法從 SM-DP+/SM-DS 下載設定檔。
ERROR_OPERATION_BUSY 系統正在下載設定檔，因此不允許任何可能觸發 SIM 狀態變更的其他動作。
OPERATION_METADATA 不適用 執行中繼資料作業時發生內部錯誤。
ERROR_INVALID_ACTIVATION_CODE 訂閱中繼資料為空白，或是訂閱中繼資料中的啟用碼為空白或無效。
ERROR_INCOMPATIBLE_CARRIER 電信業者在黑名單中，LPA 無法從 SM-DP+/SM-DS 下載該電信業者的設定檔。
OPERATION_EUICC_GSMA 不適用 執行 eUICC GSMA 作業時發生內部錯誤。
ERROR_INSTALL_PROFILE 嘗試安裝設定檔時發生 eUICC 錯誤。例如設定檔已存在或 ICCID 不符。
ERROR_EUICC_INSUFFICIENT_MEMORY 嘗試安裝設定檔時發生 eUICC 錯誤。eUICC 的記憶體不足。
ERROR_DISALLOWED_BY_PPR 嘗試安裝設定檔時發生 eUICC 錯誤。系統會依設定檔政策規則禁止這項操作。
OPERATION_APDU 不適用 執行 APDU 作業時發生內部錯誤。
OPERATION_HTTP 1-999 錯誤代碼是 HTTP 錯誤值。
作業代碼 主題代碼 原因代碼 說明
OPERATION_SMDX_SUBJECT_REASON_CODE 字串包含 3 個以點號分隔的數字，且不含前置的零。例如：8.1.1。 字串包含 3 個以點號分隔的數字，且沒有開頭的零。例如：3.8。 GSMA 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2] (SGP.22 v2.2)。舉例來說，SubjectCode 為 8.1.1 且 ReasonCode 為 3.8 表示 EID 已綁定至其他裝置。