eUICC API エラーを処理する

eUICC API は、アプリとユーザーが eSIM プロファイルのダウンロード、有効化、無効化、削除に関する問題をトラブルシューティングする際に役立つエラーコードを提供します。

エラーを処理する

eUICC API の呼び出し中にエラーが発生すると、ペンディング インテント コールバックが提供され、詳細なエラーコードを取得するためのキーとして EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE が使用されます。Android 11 以降では、結果のインテントに次の 4 つのキーと値が含まれます。

  • EXTRA_EMBEDDED_SUBSCRIPTION_OPERATION_CODE: 問題に関する情報(何がエラーになったか)を提供します。たとえば、eSIM プロファイルのダウンロードや削除などです。このフィールドには常に値が入力されます。
  • EXTRA_EMBEDDED_SUBSCRIPTION_ERROR_CODE: エラーが発生した理由に関する情報。たとえば、リクエストがタイムアウトした、デバイスがキャリアロックされているなどです。次の場合、このフィールドは空になります。

    • オペレーション コードが OPERATION_SMDX_SUBJECT_REASON_CODE の場合。
    • IOExceptionInterruptedException などの下位レベルのエラーである場合。
  • EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE: EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE とともに使用され、この両者で GSMA(SGP.22 v2.2)からの SubjectCode[5.2.6.1] と ReasonCode[5.2.6.2] を提供します。オペレーション コードが OPERATION_SMDX_SUBJECT_REASON_CODE の場合にのみ値が入力されます。

  • EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE: EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_SUBJECT_CODE とともに使用され、この両者で GSMA(SGP.22 v2.2)からの SubjectCode[5.2.6.1] と ReasonCode[5.2.6.2] を提供します。オペレーション コードが OPERATION_SMDX_SUBJECT_REASON_CODE の場合にのみ値が入力されます。

eUICC API の呼び出し元は、これら 4 つの値を使用して特定のエラーを個別に処理できます。これらのエラーを処理する方法の例を次に示します。

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 のルール認証テーブルが null であるか、またはプロファイル ポリシールールによってダウンロードが禁止されています。
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 が別のデバイスにバインドされていることを意味します。