处理 eUICC API 错误

eUICC API提供错误代码以帮助应用和用户解决与下载、启用、禁用和删除 eSIM 配置文件相关的问题。

处理错误

当调用 eUICC API 发生错误时,会提供一个挂起的 Intent 回调,并使用EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE作为获取详细错误码的 key。从 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) 的 SubjectCode[5.2.6.1] 和 ReasonCode[5.2.6.2]。例如,SubjectCode 为8.1.1和 ReasonCode 为3.8表示 EID 绑定到另一个设备。