處理 eUICC API 錯誤

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

處理錯誤

當呼叫 eUICC API 時發生錯誤時，會提供待處理的 Intent 回調，並使用EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE作為取得詳細錯誤代碼的鍵。從 Android 11 開始，產生的 Intent 中包含以下四個鍵和值：

這四個值允許 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。
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 (SGP.22 v2.2) 的主題代碼 [5.2.6.1] 和原因代碼 [5.2.6.2]。例如，SubjectCode 為8.1.1 ，ReasonCode 為3.8表示 EID 已綁定到另一個裝置。