處理 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 個數字，且開頭不得為 0。例如：3.8。 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。舉例來說，如果 SubjectCode 為 8.1.1，且 ReasonCode 為 3.8，表示 EID 已繫結至其他裝置。