Mã lỗi
Bảng tham chiếu mã lỗi cho FaceAuthen. Bao gồm mọi mã do API trả về. Mã do Mobile SDK hoặc Web SDK phát sinh nằm ngoài phạm vi trang này.
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ânjson
{
"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. |
403101 | Từ chối quyền truy cậ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 xác thực khuôn mặt. |
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. |
2009000 | Không tìm thấy lần đăng ký hoặc lần đăng ký đã hết hạn. |
2009001 | Bằng chứng đăng ký không hợp lệ. |
2009003 | Một lần đăng ký khác cho khóa này đang được xử lý. Vui lòng thử lại. |
2009004 | Không tìm thấy khóa ký. |
2009005 | Phiên bản SDK không còn được hỗ trợ. Vui lòng cập nhật ứng dụng. |
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ã kết luận xác thực khuôn mặt
WARNING
Hai nguồn tài liệu của CAKE ghi nhận 2002201 và 2002205 theo hai chiều ngược nhau:
| Mã | Trang Error Code (06/2024) | Trang API Xác minh Face Authen (05/2026) |
|---|---|---|
2002201 | verdict unmatched | verdict unsure |
2002205 | verdict unsure | verdict unmatched |
Bảng dưới đây theo trang API, vốn được cập nhật gần đây hơn trong hai nguồn. Nếu hệ thống của bạn rẽ nhánh dựa trên các mã này, hãy xác nhận với đội backend của CAKE trước khi đưa vào production — đọc sai chiều sẽ khiến unmatched và unsure bị đảo ngược cho nhau.
| Mã | Thông báo |
|---|---|
2002201 | Xác thực khuôn mặt không khớp (verdict unsure). |
2002205 | Xác thực khuôn mặt không khớp (verdict unmatched). |
2002206 | Hồ sơ người dùng đã bị khóa. |
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. |
permission_denied_exception | Bên gọi không được phép dùng endpoint này — ví dụ Bearer token của SDK trên một endpoint chỉ dành cho backend. |
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. |
sdk_version_unsupported | SDK cũ hơn phiên bản tối thiểu mà tenant của bạn chấp nhận cho các request có signature của thiết bị. Xem Ký request. |
Chỉ dùng cho đăng ký và xác thực
| Mã | Mô tả |
|---|---|
register_rate_limit_exceeded | Vượt giới hạn tần suất đăng ký. |
register_brute_force_limit_exceeded | Vượt giới hạn brute-force khi đăng ký. |
face_auth_rate_limit_exceeded | Vượt giới hạn tần suất xác thực khuôn mặt. |
face_auth_brute_force_limit_exceeded | Vượt giới hạn brute-force của xác thực khuôn mặt. |
face_already_registered | Khuôn mặt đã được đăng ký trong hệ thống. |
user_already_registered | user_id đã được đăng ký. |
compare_faces_not_matched | Các khuôn mặt phát hiện được từ ảnh gửi lên server không khớp nhau. |
sanity_check_failed | Kiểm tra sanity của selfie / id_card thất bại. |
liveness_check_failed | Kiểm tra liveness của selfie / id_card thất bại. |
selfie_image_invalid | Ảnh selfie gửi lên server có độ dài không khớp với cấu hình. |
incorrect_number_of_faces | Ảnh selfie hoặc ảnh gốc có nhiều hơn 1 khuôn mặt. |
Chỉ dùng cho khóa thiết bị
Được trả về bởi các endpoint khóa ký (signing credential): Init, Confirm, Get Active và Revoke.
| Mã | Mô tả |
|---|---|
registration_expired | Lần đăng ký không tồn tại, thuộc về thiết bị khác, hoặc đã quá expires_at. Hãy bắt đầu lại bằng Init. |
registration_proof_invalid | Bằng chứng đăng ký không vượt qua một bước kiểm tra; detail.reason cho biết bước đó. |
registration_conflict | Một lần xác nhận đồng thời cho cùng key_id đang chạy. Có thể thử lại an toàn. |
signing_credential_not_found | key_id không tồn tại cho thiết bị này trong tenant của bạn. |
Khóa hồ sơ
Chuỗi sự kiện dẫn đến một hồ sơ bị khóa:
| Bước | Mã | Hiệu ứng |
|---|---|---|
| Vượt giới hạn tần suất | 2001016 | Tạm thời — người dùng có thể thử lại sau. |
| Vượt giới hạn brute-force | 2001017 | Hồ sơ bị khóa. |
| Mọi lệnh gọi tiếp theo | 2002206 | Bị từ chối cho đến khi được mở khóa. |
Dùng Mở khóa hồ sơ để gỡ khóa.
Bước tiếp theo
- Xác minh Face Authen — nơi phát sinh phần lớn lỗi xác thực
- Mở khóa hồ sơ — gỡ khóa một hồ sơ bị khóa