Error Codes

Error code reference for the FaceAuthen. 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.
403101	Permission denied. 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.
2009000	Registration not found or expired.
2009001	Registration proof is invalid.
2009003	Another registration for this key is in progress. Please retry.
2009004	Signing credential not found.
2009005	SDK version is no longer supported. Please update the app.
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.

Face Authentication Verdict Codes

WARNING

Two CAKE sources document 2002201 and 2002205 the opposite way round:

Code	Error Code page (06/2024)	Verify Face Authen API page (05/2026)
2002201	verdict unmatched	verdict unsure
2002205	verdict unsure	verdict unmatched

The table below follows the API page, which is the more recently updated of the two. If your system branches on these codes, confirm with the CAKE backend team before going to production — reading them the wrong way round inverts unmatched and unsure.

Code	Message
2002201	Face authentication did not match (verdict unsure).
2002205	Face authentication did not match (verdict unmatched).
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.
permission_denied_exception	The caller is not allowed on this endpoint — for example an SDK Bearer token on a backend-only endpoint.
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.
sdk_version_unsupported	The SDK is older than the minimum version your tenant accepts for device-signed requests. See Request Signing.

Registration and Authentication Only

Code	Description
register_rate_limit_exceeded	Register rate limit exceeded.
register_brute_force_limit_exceeded	Register brute force limit exceeded.
face_auth_rate_limit_exceeded	Face auth rate limit exceeded.
face_auth_brute_force_limit_exceeded	Face auth brute force limit exceeded.
face_already_registered	Face has been registered on the system.
user_already_registered	The user_id has been registered.
compare_faces_not_matched	Faces detected from images sent to the server are not matched.
sanity_check_failed	Verify selfie / id_card sanity failed.
liveness_check_failed	Verify selfie / id_card liveness failed.
selfie_image_invalid	Selfie image sent to the server has length not equal to configuration.
incorrect_number_of_faces	Selfie or original image have more than 1 faces.

Device Key Only

Returned by the Init, Confirm, Get Active and Revoke signing credential endpoints.

Code	Description
registration_expired	The registration is unknown, belongs to another device, or passed expires_at. Start again with Init.
registration_proof_invalid	The registration proof failed a check; detail.reason names it.
registration_conflict	A concurrent confirmation for the same key_id is running. Safe to retry.
signing_credential_not_found	The key_id does not exist for this device in your tenant.

Profile Locking

The sequence that leads to a locked profile:

Step	Code	Effect
Rate limit exceeded	2001016	Transient — the user can retry later.
Brute-force limit exceeded	2001017	The profile locks.
Every subsequent call	2002206	Rejected until unlocked.

Use Unlock Profile to clear the lock.

Next Steps

• Verify Face Authen — where most authentication errors originate
• Unlock Profile — clearing a locked profile