处理 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 上的规则授权表为空，或者配置文件策略规则不允许下载。
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 已绑定到另一台设备。