Como lidar com erros da API eUICC

As APIs eUICC fornecem códigos de erro para ajudar aplicativos e usuários a solucionar problemas relacionados ao download, ativação, desativação e exclusão de perfis de eSIM.

Manipulação de erros

Quando ocorre um erro ao chamar a API eUICC, um retorno de chamada de intenção pendente é fornecido e EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE é usado como a chave para obter o código de erro detalhado. A partir do Android 11, as quatro chaves e valores a seguir são incluídos no intent resultante:

• EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE : Fornece informações sobre o que deu errado. Por exemplo, baixar ou excluir um perfil eSIM. Este campo nunca está vazio.

• EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE : Informações sobre o motivo do erro. Por exemplo, a solicitação expirou ou o dispositivo está bloqueado pela operadora. Este campo não é preenchido nos seguintes casos:

  • O código de operação é OPERATION_SMDX_SUBJECT_REASON_CODE .
  • O erro é um erro de baixo nível, como IOException ou InterruptedException .

• EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE : Usado com EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE , que juntos fornecem SubjectCode[5.2.6.1] e ReasonCode[5.2.6.2] da GSMA (SGP.22 v2.2). Este campo é preenchido apenas quando o código de operação é OPERATION_SMDX_SUBJECT_REASON_CODE .

• EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE : Usado com EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE , que juntos fornecem SubjectCode[5.2.6.1] e ReasonCode[5.2.6.2] da GSMA (SGP.22 v2.2). Este campo é preenchido apenas quando o código de operação é OPERATION_SMDX_SUBJECT_REASON_CODE .

Esses quatro valores permitem que o chamador da API eUICC lide com erros específicos individualmente. Veja a seguir um exemplo de como lidar com esses erros.

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

Operações suportadas e combinações de códigos de erro

A tabela a seguir descreve a combinação suportada de operação e códigos de erro retornados do assistente de perfil local (LPA).