Handle eUICC API errors

The eUICC APIs provide error codes to help apps and users troubleshoot issues related to downloading, enabling, disabling, and deleting eSIM profiles.

Handle errors

When an error occurs while calling the eUICC API, a pending intent callback is provided and EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE is used as the key for getting the detailed error code. Starting from Android 11, the following four keys and values are included in the resulting intent:

• EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE: Provides information about what went wrong. For example, downloading or deleting an eSIM profile. This field is never empty.

• EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE: Information about why the error occurred. For example, the request timed out or the device is carrier locked. This field isn't populated in the following cases:

  • The operation code is OPERATION_SMDX_SUBJECT_REASON_CODE.
  • The error is a low-level error such as IOException or InterruptedException.

• EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE: Used with EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE, which together provide the SubjectCode[5.2.6.1] and ReasonCode[5.2.6.2] from GSMA (SGP.22 v2.2). This field is populated only when the operation code is OPERATION_SMDX_SUBJECT_REASON_CODE.

• EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE: Used with EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE, which together provide the SubjectCode[5.2.6.1] and ReasonCode[5.2.6.2] from GSMA (SGP.22 v2.2). This field is populated only when the operation code is OPERATION_SMDX_SUBJECT_REASON_CODE.

These four values allow the caller of the eUICC API to handle specific errors individually. The following is an example of how to handle these errors.

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.
}

Supported operation and error code combinations

The following table describes the supported combination of operation and error codes returned from the local profile assistant (LPA).