Mã lỗi

Bảng tham chiếu mã lỗi cho eID. Bao gồm các mã do API và CICReader Mobile SDK trả về.

Cách đọc một lỗi

Mọi endpoint đều trả về HTTP 200 khi request đã được xử lý, kể cả khi kiểm tra nghiệp vụ thất bại. Luôn đọc theo thứ tự sau:

text

1. success        → false nghĩa là request thất bại
2. code           → mã lỗi dạng số (0 = thành công)
3. data.status    → "success" hoặc "failure"
4. errors[].code  → mã lỗi dạng chuỗi mô tả nguyên nhân

json

{
  "success": false,
  "code": 4001000,
  "message": "Input parameter violates a constraint.",
  "data": { "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1" },
  "errors": [
    {
      "code": "invalid_parameter_exception",
      "message": "Input parameter violates a constraint.",
      "detail": { "field": "card_type" }
    }
  ]
}

Luôn đính kèm request_id khi báo lỗi cho CAKE Support — đây là khóa để tra cứu log phía server.

Mã lỗi dạng số

Dùng chung trên nền tảng định danh của CAKE.

Mã	Thông báo
`401100`	Hành động không được phép. Bạn không có quyền thực hiện hành động này.
`2001000`	Dữ liệu khuôn mặt vi phạm một ràng buộc.
`2001001`	Dữ liệu embedding vi phạm một ràng buộc.
`2001002`	Xảy ra lỗi không mong đợi khi xử lý request bên ngoài.
`2001003`	Không phát hiện khuôn mặt nào trong ảnh selfie hoặc ảnh gốc.
`2001005`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.
`2001006`	Ảnh selfie và mặt trước CCCD không khớp.
`2001007`	Không tìm thấy client trong hệ thống.
`2001008`	Khuôn mặt đã được đăng ký trong hệ thống.
`2001009`	Phát hiện nhiều khuôn mặt trong ảnh selfie hoặc ảnh gốc.
`2001010`	Không tìm thấy Access ID trong hệ thống.
`2001011`	Kiểm tra liveness thất bại.
`2001012`	Kiểm tra sanity thất bại.
`2001014`	Vượt giới hạn tần suất đăng ký. Quá nhiều lần thử đăng ký.
`2001015`	Vượt giới hạn brute-force khi đăng ký.
`2001016`	Vượt giới hạn tần suất xác thực khuôn mặt. Quá nhiều lần thử.
`2001017`	Vượt giới hạn brute-force của face authentication.
`2001019`	Không tìm thấy giao dịch trong hệ thống.
`2001020`	Lock giao dịch thất bại.
`2001021`	Request giao dịch không hợp lệ.
`2001022`	Giao dịch đã được xác minh.
`2001023`	Khóa giao dịch không hợp lệ.
`2001024`	Lock xác thực thất bại.
`2001025`	Ảnh selfie được cung cấp không hợp lệ.
`2001026`	Phát hiện ảnh trùng lặp.
`2001027`	Token không hợp lệ.
`2001031`	Vượt giới hạn tần suất tải lên.
`2002100`	Giao dịch đã hết hạn.
`2002101`	Challenge của giao dịch không hợp lệ.
`2002200`	Ảnh selfie đã hết hạn.
`2002202`	Ảnh selfie được cung cấp không hợp lệ.
`2002203`	Hồ sơ người dùng đã bị khóa.
`2002204`	Hồ sơ người dùng chưa được kích hoạt.
`4001000`	Tham số đầu vào vi phạm một ràng buộc.
`4001001`	Header `X-TV-Timestamp` đã hết hạn. Vui lòng cung cấp timestamp mới hơn.
`4001002`	Ảnh selfie hoặc ảnh gốc chứa nhiều hơn một khuôn mặt.
`4001005`	Ref ID không hợp lệ.
`4041000`	Không tìm thấy image ID trong DB.
`4041001`	Không tìm thấy khuôn mặt của người dùng.
`4041002`	Không tìm thấy hồ sơ của người dùng.
`4041003`	Không tìm thấy request ID khi poll kết quả theo id.
`4041004`	Không tìm thấy file ID trong DB.
`4041005`	Không tìm thấy collection trong DB.
`4091000`	`cus_user_id` đã được đăng ký.
`4131000`	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
`4131001`	Kích thước file đầu vào vượt quá giới hạn cho phép (15MB).
`4151000`	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
`4151001`	Định dạng file được cung cấp không được hỗ trợ (PDF).
`4291000`	Số lượng request vượt quá giới hạn throughput.
`5001000`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã lỗi riêng của eID

Mã	Thông báo
`2001029`	Không tìm thấy thông tin NFC.
`2001030`	Document ID không hợp lệ.

Mã lỗi dạng chuỗi

Trả về trong mảng errors[].code.

Mã	Mô tả
`access_id_not_found`	Không tìm thấy Access ID.
`access_denied_exception`	Bạn không được phép thực hiện hành động này.
`invalid_parameter_exception`	Tham số đầu vào vi phạm một ràng buộc.
`request_time_too_skewed`	Header `X-TV-Timestamp` đã hết hạn, cần một cái mới hơn.
`image_not_found_exception`	Không tìm thấy image ID trong DB.
`image_too_large_exception`	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
`invalid_image_format_exception`	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
`duplicated_image`	Ảnh gửi đến server bị trùng lặp.
`image_has_no_faces`	Ảnh gửi đến server không có khuôn mặt nào.
`image_has_multiple_faces`	Ảnh gửi đến server có nhiều khuôn mặt.
`request_not_found_exception`	Không tìm thấy request ID khi poll kết quả theo id.
`request_timeout_exception`	Request mất quá nhiều thời gian để xử lý.
`rate_limit_exception`	Số lượng request vượt quá giới hạn throughput.
`internal_server_error`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.
`transaction_lock_failed`	Lock giao dịch thất bại.
`transaction_invalid_request`	Request giao dịch không hợp lệ.
`user_profile_not_found_exception`	Không tìm thấy hồ sơ của người dùng.
`user_profile_locked`	Hồ sơ người dùng đã bị khóa.
`user_not_found_exception`	Không tìm thấy người dùng.

HTTP status code

Mã	Mô tả
`401`	Bạn không được phép thực hiện hành động này.
`500`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

CICReader SDK — Android

Được Android SDK ném ra dưới dạng CICException. Tách biệt với các mã lỗi API ở trên.

Mã	Thông báo
`600032`	`NfcNotAvailableException` — NFC không khả dụng.
`600316`	`IllegalMRZException` — Phát hiện thông tin MRZ không hợp lệ.
`600317`	`IllegalCanException` — Phát hiện thông tin CAN không hợp lệ.
`600333`	`EstablishMessageChannelFailedException` — Thiết lập kênh message PACE thất bại.
`600396`	`InvalidCardType` — Thẻ được quét không phải CCCD.
`600503`	`UnexpectedException` — Xảy ra exception không mong đợi.
`600666`	`ReadingDataFailedException` — Đọc dữ liệu từ CCCD thất bại.
`601400`	`NetworkError` — Xảy ra lỗi mạng.
`601401`	`ApiError` — API trả về lỗi.
`601404`	`UnauthorizedError` — Người dùng không được phép.
`601408`	`NotFoundError` — Không tìm thấy tài nguyên được yêu cầu.
`601503`	`ServerError` — Xảy ra lỗi server.

CICReader SDK — iOS và JavaScript

Được iOS SDK ném ra dưới dạng CESNfcError, và được JavaScript bridge trả về dưới dạng {code, message}.

Mã	Thông báo
`-1`	`Unspecified` — Lỗi không mong đợi. Chỉ JavaScript bridge.
`3`	`UserCancelled` — Người dùng đã hủy. Chỉ JavaScript bridge.
`600001`	`ResponseError` — Xảy ra lỗi khi xử lý response NFC.
`600002`	`InvalidResponse` — Một số dữ liệu trên thẻ không hợp lệ.
`600032`	`NFCNotSupported` — NFC không được hỗ trợ trên thiết bị này.
`600101`	`SessionOnGoing` — Một phiên đọc khác đang diễn ra.
`600102`	`SystemResourceUnavailable` — Hệ thống NFC đang bận.
`600103`	`NfcNotAvailable` — Thiết bị không hỗ trợ NFC. Chỉ JavaScript bridge.
`600301`	`InvalidResponseChecksum` — Checksum của response không hợp lệ.
`600302`	`MissingMandatoryFields` — Thiếu các trường bắt buộc trong response.
`600304`	`CannotDecodeASN1Length` — Không thể giải mã độ dài ASN.1.
`600308`	`InvalidASN1Value` — Gặp giá trị ASN.1 không hợp lệ.
`600316`	`InvalidMRZKey` / `InvalidFullMRZKey` — Khóa MRZ không hợp lệ.
`600317`	`InvalidCANKey` — Khóa Card Access Number không hợp lệ.
`600332`	`MoreThanOneTagFound` — Tìm thấy nhiều hơn một NFC tag.
`600333`	`EstablishMessageChannelFailedException` — Thiết lập kênh PACE thất bại. Chỉ JavaScript bridge.
`600364`	`InvalidHashAlgorithmSpecified` — Chỉ định thuật toán hash không hợp lệ.
`600365`	`InvalidDataPassed` — Dữ liệu truyền vào hàm không hợp lệ.
`600366`	`InvalidRequestUrl` — Chỉ định request URL không hợp lệ. Chỉ iOS.
`600396`	`InvalidCardType` — Thẻ được quét không phải CCCD.
`600400`	`NoConnectedTag` — Không tìm thấy NFC tag đang kết nối.
`600401`	`D087Malformed` — Lệnh D087 sai định dạng.
`600404`	`NotImplemented` — Tính năng hoặc thao tác chưa được triển khai.
`600408`	`TagNotValid` — NFC tag không hợp lệ.
`600416`	`ConnectionError` — Xảy ra lỗi kết nối với NFC tag.
`600432`	`UserCanceled` — Thao tác bị người dùng hủy.
`600464`	`Uninitialized` — Thư viện chưa được khởi tạo trước khi sử dụng.
`600503`	`UnexpectedError` — Xảy ra lỗi không mong đợi.
`600601`	`UnableToProtectAPDU` — Không thể protect APDU.
`600602`	`UnableToUnprotectAPDU` — Không thể unprotect APDU.
`600604`	`UnsupportedDataGroup` — Data group được yêu cầu không được hỗ trợ.
`600605`	`NotYetSupported` — Tính năng hoặc thao tác chưa được hỗ trợ.
`600608`	`DataGroupNotRead` — Data group được yêu cầu chưa được đọc.
`600616`	`UnknownTag` — Gặp tag không xác định.
`600632`	`UnknownImageFormat` — Gặp định dạng ảnh không xác định.
`600666`	`ReadingDataFailedException` — Đọc dữ liệu từ CCCD thất bại. Chỉ JavaScript bridge.
`600700`	`UIError` — Xảy ra lỗi trong giao diện.
`601400`	`NetworkError` — Xảy ra lỗi mạng.
`601401`	`ApiError` — Xảy ra lỗi API.
`601404`	`ApiAccessDenied` — Truy cập API bị từ chối.
`601405`	`ApiParseError` — Xảy ra lỗi khi parse response API.
`601503`	`ServerError` — Xảy ra lỗi server.

CICReader SDK — Flutter

Flutter plugin dùng chung ba mã trên cả hai nền tảng, sau đó trả về mã của nền tảng gốc.

Mã	Thông báo
`-1`	`Unspecified` — Lỗi không mong đợi. Thông báo mang theo chi tiết.
`3`	`UserCancelled` — Người dùng đã hủy thao tác.
`4`	`SessionOnGoing` — Một phiên đọc khác đang diễn ra.

INFO

Mã của SDK (600xxx, 601xxx) và mã của API (2001xxx, 4001xxx) là hai dải độc lập. Cùng một lỗi mạng có thể xuất hiện dưới dạng 601400 từ SDK hoặc 5001000 từ API, tùy vào nơi lỗi xảy ra.

Bước tiếp theo

Đọc NFC — nơi phát sinh phần lớn lỗi đọc chip
Xác minh NFC — lỗi phát sinh khi đối chiếu với C06

Mã lỗi ​

Cách đọc một lỗi ​

Mã lỗi dạng số ​

Mã lỗi riêng của eID ​

Mã lỗi dạng chuỗi ​

HTTP status code ​

CICReader SDK — Android ​

CICReader SDK — iOS và JavaScript ​

CICReader SDK — Flutter ​

Bước tiếp theo ​