Xử lý lỗi API eUICC

Các API eUICC cung cấp mã lỗi để giúp ứng dụng và người dùng khắc phục các vấn đề liên quan đến việc tải, 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 trình gọi API eUICC xử lý riêng từng lỗi cụ thể. Sau đây là ví dụ về cách xử lý các 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ã hoạt động và mã lỗi được hỗ trợ

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

Tổ hợp mã hoạt động và mã lỗi
Mã hoạt động 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 hoạt động hoặc có sẵn trên thiết bị.
OPERATION_EUICC_CARD Không áp dụng Đã xảy ra lỗi nội bộ trong khi thực hiện 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ể tạo 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ị nhà mạng khoá (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à rỗng hoặc quá trình tải xuống không được phép theo quy tắc chính sách về hồ sơ.
ERROR_INVALID_ACTIVATION_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ệ) hoặc khi 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ị nhà mạng khoá (khoá SIM).
ERROR_INCOMPATIBLE_CARRIER Nhà mạng nằm trong danh sách đen 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 trống hoặc mã kích hoạt bên trong siêu dữ liệu gói thuê bao 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 thao tác eUICC GSMA.
ERROR_INSTALL_PROFILE Lỗi với eUICC khi cố gắng cài đặt hồ sơ. Ví dụ: hồ sơ đã tồn tại hoặc ICCID không khớp.
ERROR_EUICC_INSUFFICIENT_MEMORY Lỗi với eUICC khi cố gắng cài đặt hồ sơ. Không đủ bộ nhớ trên eUICC.
ERROR_DISALLOWED_BY_PPR Lỗi với eUICC khi cố gắng 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 thao tác APDU.
OPERATION_HTTP 1-999 Mã lỗi là giá trị lỗi HTTP.
Mã hoạt động Mã chủ đề 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 ở đầu. Ví dụ: 8.1.1. Chuỗi chứa 3 chữ số được phân tách bằng dấu chấm, không có số 0 ở đầu. Ví dụ: 3.8. SubjectCode[5.2.6.1] và ReasonCode[5.2.6.2] từ GSMA (SGP.22 v2.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.