Error Codes
Understanding Error Sources
Errors in VIDA originate from two layers:
SDK
Callback (e.g. onError)
errorCode + errorMessage
Backend API
HTTP response
errorCode + errorMessage + HTTP status code
SDK errors are raised locally on the device — network issues, permission problems, SDK state, and so on. These do not include an HTTP status code because no HTTP call was made or the SDK intercepted the issue before reaching the server.
Backend errors are returned from VIDA's API in the response body and always include an HTTP status code.
KYC
KYC - SDK Error
42001
Network timeout - please check your internet connection and try again.
42002
Authorization error - verify your authentication method.
42003
Network issue detected - please reconnect and try again.
42004
The operation failed due to insufficient memory.
42005
Internet connection error - please check your network settings.
42006
Connection lost - please ensure you are connected to the internet.
42008
Unauthorized access.
42009
Forbidden request.
42010
Requested resource not found.
42011
Internal server error.
42012
HTTP 4XX - Client-side request error.
42013
HTTP 5XX - Server-side processing error.
52001
Null response received from server.
52003
Failed to parse server response.
52004
Invalid input parameters detected.
52005
Detection process timed out.
52006
Error while parsing network response.
52007
Unexpected error occurred - please try again later.
52008
KYC SDK not initialized - please initialize before proceeding.
52009
The KYC SDK process is already running.
52010
The liveness failure due to App Package Name mismatch / incorrect Activation Key.
52011
Liveness SDK dependency is missing
52012
VIDA ID Shield dependency is missing
72001
The user canceled the process by pressing the back button.
72002
Failed to start camera - please retry.
72003
Backend response contains error
72005
Camera permission missing — enable camera access to proceed.
72006
Maximum retry attempts reached.
72007
Card detection failed - please retake the image.
72008
Potential threat or anomaly detected.
72009
The user postponed the process by selecting “Try Later.”
72010
Detection process canceled.
KYC - Backend Errors
5014
Image Quality is too low, Kindly ensure the image is well lit and is placed in the right angle
5016
Invalid card, Kindly ensure the image is well lit and is placed in the right angle
5020
No card detected
5023
Bad Quality Image , Id Number Extraction Failed
5025
The card failed the idVerification
5026
Extraction failed for the below ocr field. Please make sure the fields are properly visible on the card.
5101
No card detected
5103
Bad Quality Image, Portrait Extraction Failed
5201
No portrait is present on the card
5202
Image Quality check failed as image is too blurry
5203
Image of the card is too dark
5204
Image of the card is too bright
5205
Image of card is too small, try taking a closer image
5206
No PROVINSI title is present, make sure all card’s edge is present within the image
5207
Quality check failed. Card has glare
5301
Card resolution is smaller than (400x300), the recommended image size is (800x600)
5302
Card resolution is larger than (4000x3000), the recommended image size is (800x600)
5303
Image size is larger than max allowed 3MB
5401
Orientation unknown, take image of card on a flat surface in upright position
Generic Codes - Malaysian Cards, Passport, & KTP
5000
200
Success
5001
400
Missing required field
5002
400
Unable to decode string.
5003
400
Invalid request parameter or Missing request parameter.
5005
500
Internal server error
5006
400
Unsupported image format detected.
5007
400
Score is below threshold
5008
500
Data processing error
5009
400
Wrong input format
5010
400
Invalid Image Specification
5012
400
Score is above threshold
5016
400
Invalid card, Kindly ensure the image is well lit and is placed in the right angle
5020
400
No card detected
5022
500
Internal server error while fetching the details.
5024
400
The given card is forged
5027
400
The ID numbers on the front and back of your card do not match. Please upload both sides of the same card
5028
400
The card appears to be spoofed
5029
400
Critical landmarks are not visible. Please make sure the landmarks are properly visible on the card
5030
400
The card failed the material check.
5103
400
Bad Quality Image , Portrait Extraction Failed
5207
400
Quality check failed. Card has glare, try taking image in a different angle
5321
400
Card resolution for back side is smaller than (275 x 176), the recommended image size is (800x600)
5322
400
Card back side verification is not supported on V1 endpoint, please switch to V2
5323
400
Configuration set for front only verification, please send only front side image or contact VIDA Support
5324
400
Configuration set for both side verification, please send both front and back side image or contact VIDA Support
5325
400
Front side image not found for verification. Please send the front side image first.
5402
400
Front side and back side of the card have different card types, please send the same card type for verification.
5403
400
The card type sent is not supported for backside verification
5501
400
[OSS] Product id not found
5502
400
[OSS] Product credentials not found
5503
400
[OSS] Product expired
5504
400
[OSS] Invalid License
5505
400
Invalid product
5601
400
Spoof check failed. Image submitted is Recaptured
5602
400
Spoof check failed. Image submitted is either B&W or Photocopy
5603
400
Spoof check failed. Image submitted is color reprint
5604
400
Spoof check failed. Image submitted is screenshot
5611
400
Minimum landmark checks did not meet the score threshold
5621
400
Passive authentication failed.
5622
400
Active authentication failed.
5623
400
Chip authentication failed.
5624
400
NFC verification is not supported on V1 API.
5625
400
PACE failed.
5626
400
BAC failed.
5627
400
Access control failed. Neither PACE nor BAC was performed.
5628
400
NFC verification is not enabled for this product. Please contact support to enable it.
Generic Code - KTP cards
5201
400
No portrait is present on the card
5202
400
Image Quality check failed as image is too blurry
5203
400
Image of the card is too dark
5204
400
Image of the card is too bright
5205
400
Image of card is too small, try taking a closer image
5206
400
No PROVINSI title is present, make sure all card’s edge is present within the image
5207
400
Quality check failed. Card has glare, try taking image in a different angle
5301
400
Card resolution is smaller than (400×300), the recommended image size is (800×600))
5302
400
Card resolution is larger than (4000×3000), the recommended image size is (800×600))
5303
400
Image size is larger than max allowed 3MB
5401
400
Orientation unknown, take image of card on a flat surface in upright position
5404
400
The submitted document type is not supported for automated verification.
5005
500
Extraction_failed
5025
400
The card failed the idVerification
5026
400
Extraction failed for the below ocr field. Please make sure the fields are properly visible on the card.
5023
400
Bad Quality Image , Id Number Extraction Failed
5101
400
No card detected
5102
500
Error processing input/output
5103
400
Bad Quality Image, Portrait Extraction Failed
5104
400
Minimum OCR fields did not meet the score thresholds
10024
200
Image submitted is blurred
10025
200
Image submitted has glare
10026
200
Image submitted is too dark to process
10027
200
Input card image is too small in resolution to process. min resolution : [275 * 176]
OCR Warning Codes - Malaysian cards & Non-KTP
10028
200
Low confidence score for ocr, please check [name] from ocrResult for more details
10029
200
Low confidence score for ocr, please check [address] from ocrResult for more details
10030
200
Low confidence score for ocr, please check [citizenship] from ocrResult for more details
10031
200
Low confidence score for ocr, please check [dob] from ocrResult for more details
10032
200
Low confidence score for ocr, please check [gender] from ocrResult for more details
10033
200
Low confidence score for ocr, please check [idNumber] from ocrResult for more details
10034
200
Low confidence score for ocr, please check [religion] from ocrResult for more details
10119
200
Low confidence score for ocr, please check [personalIdNumber] from ocrResult for more details
10120
200
Low confidence score for ocr, please check [dateOfExpiry] from ocrResult for more details
10121
200
Low confidence score for ocr, please check [dateOfIssuance] from ocrResult for more details
10122
200
Low confidence score for ocr, please check [issuerName] from ocrResult for more details
10123
200
Low confidence score for ocr, please check [issuerCountry] from ocrResult for more details
10124
200
Low confidence score for ocr, please check [issuingAuthority] from ocrResult for more details
10125
200
Low confidence score for ocr, please check [militaryId] from ocrResult for more details
10126
200
Low confidence score for ocr, please check [militaryRank] from ocrResult for more details
10127
200
Low confidence score for ocr, please check [militaryDivision] from ocrResult for more details
10128
200
Low confidence score for ocr, please check extendedIdNumber from for more details
10129
200
Low confidence score for ocr, please check countryOfOrigin from for more details
Landmark Codes - Malaysian cards
10012
200
Image has Occlusion [kad_pengenalan_header], please check landmark details for more details
10013
200
Image has Occlusion [card_logo], please check landmark details for more details
10014
200
Image has Occlusion [hibiscus], please check landmark details for more details
10015
200
Image has Occlusion [microchip], please check landmark details for more details
10017
200
Image has Occlusion [msg_logo], please check landmark details for more details
10018
200
Image has Occlusion [my_flag], please check landmark details for more details
10020
200
Image has Occlusion [ghost], please check landmark details for more details
10021
200
Image has Occlusion [portrait], please check landmark details for more details
10022
200
Image has Occlusion [name], please check landmark details for more details
10023
200
Image has Occlusion [id_number], please check landmark details for more details
10401
200
Landmark verification failed for the provided card image.
10426
200
Image has Occlusion, please check coat_of_arm from for more details
10427
200
Image has Occlusion, please check kopiah from for more details
10428
200
Image has Occlusion, please check twin_tower from for more details
10429
200
Image has Occlusion, please check state_registrar from for more details
10430
200
Image has Occlusion, please check sn from for more details
10431
200
Image has Occlusion, please check my_logo from for more details
10432
200
Image has Occlusion, please check negara_asal from for more details
10433
200
Image has Occlusion, please check military_logo from for more details
10510
200
Image extraction failed during verification
Deduplication Error Code
5801
400
Verification failed: Image is blacklisted.
5802
400
Verification failed: Face from card associated with multiple ID Numbers.
5803
400
Verification failed: ID Number from card associated with multiple faces.
5804
400
No face detected
ID Fraud Shield Errors
5901
400
ID Fraud shield risk level exceeded error threshold.
5902
400
ID Fraud shield evaluation is incomplete.
5903
400
ID Fraud shield transaction details not found.
NFC Verification
10520
200
Data discrepancy detected between chip and document image.
10521
200
Portrait mismatch detected between chip and document image.
Liveness
Liveness - SDK Errors
40001
Unable to proceed please check your connection
40002
Unable to proceed due to network timeout, please check your connection or <Empty message in some cases>
YES
40003
Unable to proceed, ensure that the authorization method is correct
YES
40004
Unable to proceed due to unknown network, please reconnect again
YES
40005
Unable to proceed, please check your internet connection
YES
40006
Unable to proceed, please check your internet connection or <actual error message >
YES
40007
Unable to proceed please check your connection
YES
50001
Received a null response from the server
50002
Internal server error
YES
50003
Something went wrong, please try again later
50004
Invalid parameters %1$s
50005
Something went wrong, please try again later
50007
Something went wrong, please try again later
50008
Something went wrong, please try again later
50009
Unable to parse the information
50010
Something went wrong, please try again later
50012
Liveness detection is in progress
50013
License key not found
50014
Something went wrong, please try again later
50017
Internal Server Error
50018
Something went wrong, please try again later
50019
Liveness SDK is not initialized. Initialize it first
50020
Liveness check is not configured, please check with support team
50021
Landscape orientation not supported.
Please rotate in portrait orientation.
50022
Liveness image upload failed color flash flow
50023
Back camera not supported for the selected configuration (color flash flow)
60001
Crypto error. Unable to encrypt request
60002
Crypto error. Unable to decrypt response
60003
Unknown error while generating hash
60004
Unknown error while encrypting the data
60005
Unknown error while fetching store key
60006
Device Id not found in the keychain
60007
Device ID could not be decrypted. Device ID or Keychain might be tampered.
70001
Unable to proceed, the functionality will not work without Camera permissions
70002
Face detection failed with error : %1$s
70003
Failed to get image result
70004
Liveness detection is canceled
70005
Retrying liveness detection activity
70006
Image capture process has failed
70007
Detection timed out
70008
User canceled liveness process by clicking back button
70009
Camera start process is failed
70010
Maximum attempt to retry liveness has exhausted
70011
You cannot use the zoomFace gesture with other gestures. Please refer to documentation for more details
70012
Liveness detection failed
70013
Please make sure to add ID Fraud shield SDK dependency
70013
ID fraud shield clientID is missing, please check with support team
70014
Liveness detection interrupted
Liveness - Backend Errors
1000
Something went wrong!
1038
Invalid base64 encoded image string or unable to detect face
1039
Liveness service error
1040
Selfie photo does not match with reference photo
1041
Liveness check failed
YES
1042
Selfie photo matches with reference photo
1043
Selfie photo is a live photo
1047
Unable to detect face from selfie image
1057
Something went wrong!
1058
Please ensure the shot is well-lit and clear
YES
1060
Keep your face straight
YES
1061
Video liveness score is below the threshold
1062
Please ensure to open your eyes
YES
Color Flash Error
1801
Passive liveness evaluation failed
Passive liveness failed
1802
Image manipulation evaluation failed
Image manipulation failed
1803
Color captcha evaluation failed
Color captcha failed
1804
Multiple model failures
Multi Model Failure
1805
All model evaluations failed
Complete model failure
1806
Face Color Issue
Face has no color reflection
YES
1807
Upstream Service Error
The request to the document service failed.
1808
Upstream Service Error
Received an empty or invalid response from the document service.
1809
Not Found
Captcha payload not found for the given transactionId. The session may have expired.
1810
Upstream Service Error
The document service returned fewer pre-signed URLs than requested.
1811
Encryption Failed
Failed to encrypt/decrypt payload.
1812
Color Palette Size Issue
Color Palette Size Issue
Invalid Request or Image Error
1064
JSON invalid
Invalid JSON input
1065
Image path invalid
Invalid image path
1066
HMAC key missing
Image quality low
1067
HMAC key invalid format
HMAC key format is invalid
1068
HMAC key invalid length
HMAC key length is invalid
1069
HMAC not present in EXIF
HMAC signature missing in EXIF metadata
1070
HMAC signature mismatch
HMAC signature validation failed
1071
HMAC verification error
Error verifying HMAC signature
1072
S3 role resolution failed
Unable to resolve AWS role for S3 access
1073
S3 region resolution failed
Unable to resolve AWS region for S3
1081
S3 role assume denied
AssumeRole denied for S3 access
1082
S3 access denied
Access denied by S3
1083
S3 no such key
S3 object key not found
1084
S3 read failed
Failed to read object from S3
1085
Input encoding failed
Failed to encode input
1087
Internal error
Unexpected internal error occurred
4004
HMAC signature does not match
HMAC verification failed
1006
Missing required parameter
Validation Failed
1007
Bad Request
The request body is malformed or contains invalid data types.
1008
Remote Service Error
A downstream service is unavailable or returned an unhandled error.
1056
No Image Detected
JPEG decoding error
1041
message: Smart liveness score is below threshold
Image Quality Error
1086
Face IQA error
Face Image Quality Assessment error
1051
Detect Un-standardized Image Quality
Face Occluded
1052
Detect Un-standardized Image Quality
Face too small
1053
Detect Un-standardized Image Quality
Image quality low
1054
Detect Un-standardized Image Quality
More than one face
1055
Detect Un-standardized Image Quality
No face detected
1063
Image Quality Is Below Threshold
Unnatural colour
1074
Image Quality Is Below Threshold
Under Exposure
1075
Image Quality Is Below Threshold
Over Exposure
1076
Image Quality Is Below Threshold
Image Is Blur
Backend Integration
In this section, you'll find the common errors that may occur during the development and operation of your application. This covers both the error from the SDK and the VIDA backend.
For further detailed info regarding error codes of OCR and Document Verification, please refer to this page here
KYC Error Codes
5701
TRANSACTION_NOT_FOUND_ERROR
404
GET /transaction
GET /status
Audit store has no row for the provided transactionId.
5702
KYC_FLOW_TERMINAL_ERROR
400
POST /verify
The KYC case is already in a terminal state (VERIFIED or FAILED). No further operations accepted. New requests using this groupId will be rejected.
5703
NO_VALID_LIVENESS_TRANSACTION_FOUND
400
POST /verify
No valid liveness image was found for the supplied livenessTransactionIds during IMAGE_FACEMATCH_VERIFICATION.
5704
TRANSACTION_RESPONSE_NOT_AVAILABLE
404
GET /transaction
GET /status
Audit row exists but the stored response payload is blank.
5705
DOCUMENT_NOT_FOUND
404
GET /transaction
GET /status
A presigned URL for the document image could not be generated - document not found in storage.
Liveness Fraud Codes
1705
Liveness Service API response
VIDA fraud threshold breached during liveness check. Returned in the errors array of the Liveness Service GET transaction response.
10001
Liveness Service DB state
Transaction marked as FAILURE due to fraud detection. When My-Verify fetches this liveness transaction, the real liveness scores are hidden and only the fraud error is returned.
Face Match + Liveness Combined Response Codes
When both liveness and face match are evaluated in a single call, the response may combine multiple codes:
Liveness pass + FaceMatch pass
200
imageFaceMatchVerificationResult.data.code: 1042
Liveness pass + FaceMatch fail
400
errors[].code: 1040
Liveness fail + FaceMatch pass
400
errors[].code: 1041 (liveness), result also includes 1042 (match still returned)
Liveness fail + FaceMatch fail
400
errors[].code: 1041 (liveness) + 1040 (match failed)
No valid liveness transaction found
400
errors[].code: 5703
KYC case already in terminal state
400
errors[].code: 5702
overallStatus - Quick Diagnostic
Use this table to quickly diagnose what a given overallStatus means and where to look for more details.
VERIFIED
Proceed - no investigation needed
All operations passed on latest attempt
REVIEW
operations object - which operation has status REVIEW?
OCR confidence below 100% or IDV flagged a non-blocking issue
ERROR
fraudResult.result.riskLevel first, then operations
Fraud detected OR genuine operation failure
IN_PROGRESS
operations - which operation has status null?
User did not complete all steps; liveness/faceMatch not yet done
FAILED
Case timed out - requiredOperations has unattempted steps
User abandoned flow, SDK crashed before faceMatch, or session timeout exceeded
Last updated