处理 eUICC API 错误

eUICC API 提供错误代码，可帮助应用和用户排查与下载、启用、停用和删除 eSIM 卡配置文件相关的问题。

处理错误

如果调用 eUICC API 时发生错误，系统会提供一个待处理的 intent 回调，并将 EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE 用作键，以获取详细的错误代码。从 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 上的规则授权表为 null，或配置文件政策规则禁止下载配置文件。
	`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 已绑定到其他设备。