Xử lý lỗi API eUICC

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 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 sẽ được dùng làm khoá để lấy mã lỗi chi tiết. Kể từ Android 11, 4 khoá và giá trị sau đây sẽ được đưa vào ý định cuối cùng:

Bốn giá trị này cho phép phương thức gọi của API eUICC xử lý 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ã lỗi và thao tác được hỗ trợ

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

Tổ hợp mã lỗi và thao tác
Mã hoạt động Mã lỗi 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 SIM.
ERROR_TIME_OUT Hết thời gian chờ trong khi cố gắng thực hiện thao tác trên khe SIM.
ERROR_EUICC_MISSING Không có eUICC nào có sẵn hoặc đang hoạt động 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 thể phát hiện 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à 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 khi phân tích cú pháp mã kích hoạt (định dạng không hợp lệ) hoặc cố 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á của nhà mạng (bị khoá SIM).
ERROR_INCOMPATIBLE_CARRIER Nhà mạng này 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 hành động nào khác có thể kích hoạt thay đổi 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 cấm 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 GSMA eUICC.
ERROR_INSTALL_PROFILE Lỗ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 eUICC khi cố gắng cài đặt hồ sơ. Không đủ bộ nhớ trên eUICC.
ERROR_DISALLOWED_BY_PPR Lỗi eUICC khi cố gắng cài đặt hồ sơ. Không được quy tắc chính sách hồ sơ cho phép.
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à một giá trị lỗi HTTP.
Mã hoạt động Mã chủ đề Mã lý do 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 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 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.