处理 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 上的规则授权表为 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 已绑定到其他设备。