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:

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

Operation and error code combinations
Operation code Error code Description
OPERATION_SYSTEM Not applicable An internal error occurred. For example, the thread was interrupted or an IOException error occurred.
OPERATION_SIM_SLOT Not applicable An internal error occurred while carrying out a SIM slot operation.
ERROR_TIME_OUT Timed out while trying to carry out a SIM slot operation.
ERROR_EUICC_MISSING No eUICC is available or active on the device.
OPERATION_EUICC_CARD Not applicable An internal error occurred while carrying out an eUICC operation.
ERROR_UNSUPPORTED_VERSION eUICC (chip) version and EuiccCard (software) version aren't compatible.
ERROR_EUICC_MISSING No SIM card is available in the device. For example, the LPA can't detect the SIM card.
OPERATION_SMDX Not applicable An internal error occurred while carrying out an SM-DP+/SM-DS operation.
ERROR_ADDRESS_MISSING No SM-DP+ address to download the profile.
ERROR_INVALID_CONFIRMATION_CODE An error occurred while parsing the activation code (invalid format).
ERROR_CERTIFICATE_ERROR Keystore or certificate error when used in TLS connection for verification.
ERROR_NO_PROFILES_AVAILABLE No profiles available from SM-DP+.
ERROR_CONNECTION_ERROR Can't create connection to server.
ERROR_INVALID_RESPONSE Invalid response from the SM-DP+/SM-DS server.
OPERATION_SWITCH Not applicable An internal error occurred while carrying out a switch operation.
ERROR_CARRIER_LOCKED Not allowed to switch profile because the device is carrier locked (SIM locked).
OPERATION_DOWNLOAD Not applicable An internal error occurred while carrying out a download operation.
ERROR_DISALLOWED_BY_PPR The Rules Authorization Table on the eUICC is null or the download is disallowed by the profile policy rule.
ERROR_INVALID_ACTIVATION_CODE An error occurred while parsing the activation code (invalid format) or trying to download with no activation code.
ERROR_CARRIER_LOCKED Not allowed to download because the device is carrier locked (SIM locked).
ERROR_INCOMPATIBLE_CARRIER The carrier is in the blacklist and the LPA can't download a profile from SM-DP+/SM-DS.
ERROR_OPERATION_BUSY Profile download is in progress and no other action that could trigger SIM state changes are allowed.
OPERATION_METADATA Not applicable An internal error occurred while carrying out metadata operation.
ERROR_INVALID_ACTIVATION_CODE Subscription metadata is empty or the activation code inside the subscription metadata is empty or invalid.
ERROR_INCOMPATIBLE_CARRIER The carrier is in the blacklist and the LPA can't download this carrier's profile from SM-DP+/SM-DS.
OPERATION_EUICC_GSMA Not applicable An internal error occurred while carrying out an eUICC GSMA operation.
ERROR_INSTALL_PROFILE Error with eUICC while trying to install profile. For example, the profile already exists or the ICCID doesn't match.
ERROR_EUICC_INSUFFICIENT_MEMORY Error with eUICC while trying to install profile. Not enough memory on the eUICC.
ERROR_DISALLOWED_BY_PPR Error with eUICC while trying to install profile. Not allowed by the profile policy rule.
OPERATION_APDU Not applicable An internal error occurred while carrying out an APDU operation.
OPERATION_HTTP 1-999 Error code is an HTTP error value.
Operation code Subject code Reason code Description
OPERATION_SMDX_SUBJECT_REASON_CODE String contains 3 digits separated by dot, with no leading zeros. For example, 8.1.1. String contains 3 digits separated by dot with no leading zeros. For example, 3.8. SubjectCode[5.2.6.1] and ReasonCode[5.2.6.2] from GSMA (SGP.22 v2.2). For example, a SubjectCode of 8.1.1 and a ReasonCode of 3.8 means the EID is bound to another device.