本頁面由 Cloud Translation API 翻譯而成。

處理 eUICC API 錯誤

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

處理錯誤

呼叫 eUICC API 時發生錯誤時，系統會提供待處理的意圖回呼，並使用 EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE 做為取得詳細錯誤代碼的鍵。從 Android 11 開始，產生的意圖會包含下列四個鍵和值：

EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE：提供錯誤相關資訊。例如下載或刪除 eSIM 卡設定檔。這個欄位不會是空白。
EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE：錯誤發生原因的相關資訊。例如要求逾時或裝置已鎖定。下列情況不會填入這個欄位：
- 作業代碼為 OPERATION_SMDX_SUBJECT_REASON_CODE。
- 錯誤是低階錯誤，例如 IOException 或 InterruptedException。
EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE：與 EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE 搭配使用，可一併提供 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。只有在作業代碼為 OPERATION_SMDX_SUBJECT_REASON_CODE 時，系統才會填入這個欄位。
EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE：與 EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE 搭配使用，可共同提供 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。只有在作業代碼為 OPERATION_SMDX_SUBJECT_REASON_CODE 時，系統才會填入這個欄位。

這四個值可讓 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`	不適用		執行切換作業時發生內部錯誤。
`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`。	SubjectCode[5.2.6.1] 和 GSMA (SGP.22 v2.2) 的 ReasonCode[5.2.6.2]。舉例來說，SubjectCode 為 `8.1.1` 且 ReasonCode 為 `3.8` 表示 EID 已綁定至其他裝置。