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

處理 eUICC API 錯誤

eUICC API提供錯誤代碼以幫助應用和用戶解決與下載、啟用、禁用和刪除 eSIM 配置文件相關的問題。

處理錯誤

當調用 eUICC API 發生錯誤時，會提供一個掛起的 Intent 回調，並使用EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE作為獲取詳細錯誤碼的 key。從 Android 11 開始，生成的 Intent 中包含以下四個鍵和值：

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 可用或處於活動狀態。
`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` 。	來自 GSMA (SGP.22 v2.2) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。例如，SubjectCode 為`8.1.1`和 ReasonCode 為`3.8`表示 EID 綁定到另一個設備。