Xử lý lỗi API eUICC

API eUICC cung cấp mã lỗi để giúp các ứng dụng và người dùng khắc phục sự cố liên quan đến việc tải xuống, bật, tắt và xoá hồ sơ eSIM.

Xử lý lỗi

Khi xảy ra lỗi trong khi gọi API eUICC, một lệnh gọi lại ý định đang chờ xử lý sẽ được cung cấp và EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE được dùng làm khoá để nhận mã lỗi chi tiết. Kể từ Android 11, 4 khoá và giá trị sau đây sẽ được đưa vào ý định kết quả:

4 giá trị này cho phép phương thức gọi của API eUICC xử lý riêng từng lỗi cụ thể. Sau đây là ví dụ về cách xử lý những lỗi này.

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

Các tổ hợp mã lỗi và thao tác được hỗ trợ

Bảng sau đây mô tả tổ hợp được hỗ trợ của các thao tác và mã lỗi do trợ lý hồ sơ cục bộ (LPA) trả về.

Tổ hợp mã hoạt động và mã lỗi
Mã thao tác Mã lỗi Nội dung mô tả
OPERATION_SYSTEM Không áp dụng Đã xảy ra lỗi nội bộ. Ví dụ: luồng bị gián đoạn hoặc xảy ra lỗi IOException.
OPERATION_SIM_SLOT Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện thao tác với khe cắm SIM.
ERROR_TIME_OUT Hết thời gian chờ trong khi cố gắng thực hiện thao tác với khe cắm SIM.
ERROR_EUICC_MISSING Không có eUICC nào trên thiết bị hoặc eUICC không hoạt động.
OPERATION_EUICC_CARD Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện một thao tác eUICC.
ERROR_UNSUPPORTED_VERSION Phiên bản eUICC (chip) và phiên bản EuiccCard (phần mềm) không tương thích.
ERROR_EUICC_MISSING Không có thẻ SIM nào trong thiết bị. Ví dụ: LPA không phát hiện được thẻ SIM.
OPERATION_SMDX Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện thao tác SM-DP+/SM-DS.
ERROR_ADDRESS_MISSING Không có địa chỉ SM-DP+ để tải hồ sơ xuống.
ERROR_INVALID_CONFIRMATION_CODE Đã xảy ra lỗi khi phân tích cú pháp mã kích hoạt (định dạng không hợp lệ).
ERROR_CERTIFICATE_ERROR Lỗi kho khoá hoặc chứng chỉ khi được dùng trong kết nối TLS để xác minh.
ERROR_NO_PROFILES_AVAILABLE Không có hồ sơ nào từ SM-DP+.
ERROR_CONNECTION_ERROR Không thể kết nối với máy chủ.
ERROR_INVALID_RESPONSE Phản hồi không hợp lệ từ máy chủ SM-DP+/SM-DS.
OPERATION_SWITCH Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện thao tác chuyển đổi.
ERROR_CARRIER_LOCKED Không được phép chuyển đổi hồ sơ vì thiết bị bị khoá nhà mạng (khoá SIM).
OPERATION_DOWNLOAD Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện thao tác tải xuống.
ERROR_DISALLOWED_BY_PPR Bảng uỷ quyền quy tắc trên eUICC là giá trị rỗng hoặc quy tắc chính sách hồ sơ không cho phép tải xuống.
ERROR_INVALID_ACTIVATION_CODE Đã xảy ra lỗi trong khi phân tích cú pháp mã kích hoạt (định dạng không hợp lệ) hoặc cố gắng tải xuống mà không có mã kích hoạt.
ERROR_CARRIER_LOCKED Không được phép tải xuống vì thiết bị bị khoá nhà mạng (khoá SIM).
ERROR_INCOMPATIBLE_CARRIER Nhà mạng nằm trong danh sách chặn và LPA không thể tải hồ sơ xuống từ SM-DP+/SM-DS.
ERROR_OPERATION_BUSY Quá trình tải hồ sơ xuống đang diễn ra và không được phép thực hiện bất kỳ thao tác nào khác có thể kích hoạt các thay đổi về trạng thái SIM.
OPERATION_METADATA Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện thao tác siêu dữ liệu.
ERROR_INVALID_ACTIVATION_CODE Siêu dữ liệu gói thuê bao bị trống hoặc mã kích hoạt trong siêu dữ liệu gói thuê bao bị trống hoặc không hợp lệ.
ERROR_INCOMPATIBLE_CARRIER Nhà mạng nằm trong danh sách đen và LPA không thể tải hồ sơ của nhà mạng này xuống từ SM-DP+/SM-DS.
OPERATION_EUICC_GSMA Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện một thao tác eUICC GSMA.
ERROR_INSTALL_PROFILE Đã xảy ra lỗi với eUICC khi tìm cách cài đặt hồ sơ. Ví dụ: hồ sơ đã tồn tại hoặc ICCID không khớp.
ERROR_EUICC_INSUFFICIENT_MEMORY Đã xảy ra lỗi với eUICC khi tìm cách cài đặt hồ sơ. Không đủ bộ nhớ trên eUICC.
ERROR_DISALLOWED_BY_PPR Đã xảy ra lỗi với eUICC khi tìm cách cài đặt hồ sơ. Không được phép theo quy tắc chính sách về hồ sơ.
OPERATION_APDU Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện một thao tác APDU.
OPERATION_HTTP 1-999 Mã lỗi là một giá trị lỗi HTTP.
Mã thao tác Mã môn học Mã lý do Nội dung mô tả
OPERATION_SMDX_SUBJECT_REASON_CODE Chuỗi chứa 3 chữ số được phân tách bằng dấu chấm, không có số 0 đứng đầu. Ví dụ: 8.1.1. Chuỗi chứa 3 chữ số được phân tách bằng dấu chấm và không có số 0 ở đầu. Ví dụ: 3.8. SubjectCode[5.2.6.1] và ReasonCode[5.2.6.2] của GSMA (SGP.22 phiên bản 2.2). Ví dụ: SubjectCode là 8.1.1 và ReasonCode là 3.8 có nghĩa là EID được liên kết với một thiết bị khác.