Error Codes

Error code reference for the eKYC. Covers every code returned by the API. Codes raised by the Mobile SDK or Web SDK are out of scope for this page.

How to Read an Error

Every endpoint returns HTTP 200 once the request is processed, even when the business check fails. Always read in this order:

1. success        → false means the request failed
2. code           → numeric error code (0 = success)
3. data.status    → "success" or "failure"
4. errors[].code  → string error code describing the cause

{
  "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" }
    }
  ]
}

Always include request_id when reporting an error to CAKE Support — it is the key for looking up the server-side log.

Numeric Error Codes

Shared across CAKE's identity platform.

Code	Message
401100	Unauthorized action. You do not have permission to perform this action.
2001000	Face data constraint violation.
2001001	Embedding data violates a constraint.
2001002	Unexpected error occurred while processing the external request.
2001003	No faces detected in the selfie or original image.
2001005	Unexpected error occurred while processing the request.
2001006	Selfie and front NID do not match.
2001007	Client not found in the system.
2001008	Face is already registered in the system.
2001009	Multiple faces detected in the selfie or original image.
2001010	Access ID not found in the system.
2001011	Liveness check failed.
2001012	Sanity check failed.
2001014	Registration rate limit exceeded. Too many registration attempts.
2001015	Registration brute force limit exceeded.
2001016	Face authentication rate limit exceeded. Too many attempts.
2001017	Face authentication brute force limit exceeded.
2001019	Transaction not found in the system.
2001020	Transaction lock failed.
2001021	Invalid transaction request.
2001022	Transaction has already been verified.
2001023	Invalid transaction key.
2001024	Authentication lock failed.
2001025	Invalid selfie image provided.
2001026	Duplicated image detected.
2001027	Invalid token provided.
2001031	Upload rate limit exceeded.
2002100	Transaction already expired.
2002101	Transaction challenge invalid.
2002200	Selfie image has expired.
2002202	Invalid selfie image provided.
2002203	User profile is already locked.
2002204	User profile is not active.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired. Please provide a newer timestamp.
4001002	Selfie or original image contains more than one face.
4001005	Ref ID is invalid.
4041000	The image ID is not found in DB.
4041001	The face of user not found.
4041002	The profile of user not found.
4041003	The request ID is not found when polling result by id.
4041004	The file ID is not found in DB.
4041005	The collection is not found in DB.
4091000	The cus_user_id has been registered.
4131000	The input image size exceeds the allowed limit (15MB).
4131001	The input file size exceeds the allowed limit (15MB).
4151000	The provided image format is not supported (JPG/PNG).
4151001	The provided file format is not supported (PDF).
4291000	The number of requests exceeded your throughput limit.
5001000	Some unexpected error occurs while processing the request.

eKYC-Specific Codes

Raised by Parse QR Info when the QR string is invalid.

Code	Message
2007001	Invalid QR identity number.
2007002	Invalid QR old identity number.
2007003	Invalid QR date of birth.
2007004	Invalid QR gender value.
2007005	Invalid QR issue date.
2002206	User profile is locked.

String Error Codes

Returned in the errors[].code array.

Code	Description
access_id_not_found	Access ID not found.
access_denied_exception	You are not authorized to perform the action.
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
image_not_found_exception	The image ID is not found in DB.
image_too_large_exception	The input image size exceeds the allowed limit (15MB).
invalid_image_format_exception	The provided image format is not supported (JPG/PNG).
duplicated_image	Images sent to server are duplicated.
image_has_no_faces	Image sent to the server has no faces.
image_has_multiple_faces	Image sent to the server has multiple faces.
request_not_found_exception	The request ID is not found when polling result by id.
request_timeout_exception	Request takes too long to process.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.
transaction_lock_failed	Transaction lock failed.
transaction_invalid_request	Invalid transaction request.
user_profile_not_found_exception	The profile of user not found.
user_profile_locked	User profile has been locked.
user_not_found_exception	User not found.

Parse QR Info Only

Code	Description
invalid_qr_identity_number	Identity number must be exactly 12 digits.
invalid_qr_old_identity_number	Old identity number must be empty or exactly 9 digits.
invalid_qr_date_of_birth	Date of birth format is invalid or the date does not exist. Expected DDMMYYYY.
invalid_qr_gender_value	Gender must be either Nam (male) or Nữ (female).
invalid_qr_issue_date	Issue date format is invalid or the date does not exist. Expected DDMMYYYY.

Next Steps

• Verdict Definitions — what each sanity, tampering and matching verdict means
• Usage Recommendations — image label and card type conventions