Error Code

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

Code	Name	HTTP	Endpoint	Description
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.

Important: The newly introduced error codes are applicable only to responses from the GET Transaction Details API. Existing integrations that do not consume this endpoint will continue to operate as before and will not receive these error codes.

Warning Code

Warnings are non-blocking - they do not prevent a VERIFIED status. Log them for audit purposes.

Code	Description	How to Handle
10014	Image occlusion detected - a landmark element on the ID card is partially or fully covered	Check landmarkResult.containerResult for the element with score: 0 to identify which landmark is occluded. No action required to continue.

Face Match Result Codes

Code	Message	Meaning
1042	Selfie photo matches with reference photo	Face match passed - selfie matches ID portrait
1040	Selfie photo does not match reference photo	Face match failed - selfie does not match ID portrait
1041	Photo liveness score is below the threshold	Liveness check failed - the image did not pass the liveness threshold

Liveness Fraud Codes

Code	Source	Meaning
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:

Scenario	HTTP	Response 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

Backend Error Codes - Image & Card Quality

These codes are returned by VIDA's backend during document capture operations and appear in the errors[] array of the SDK response. Your app may forward these to your backend for logging or retry logic.

Code	Description
5014	Image quality too low — ensure the image is well lit and at the correct angle
5016	Invalid card - ensure the image is well lit and at the correct angle
5020	No card detected (OCR/IDV)
5023	Bad quality image - ID number extraction failed
5025	Card failed ID verification
5026	OCR extraction failed for one or more fields - ensure all fields are visible
5101	No card detected (portrait extraction step)
5103	Bad quality image - portrait extraction failed
5201	No portrait is present on the card
5202	Image too blurry
5203	Image too dark
5204	Image too bright (overexposed)
5205	Card too small in frame - move the camera closer
5206	PROVINSI title not found - ensure all card edges are within the frame (KTP)
5301	Card resolution below minimum (400×300). Recommended: 800×600
5302	Card resolution above maximum (4000×3000). Recommended: 800×600
5303	Image file size exceeds the 3 MB maximum
5401	Card orientation unknown - capture the card on a flat surface in upright position

These codes appear in the SDK onError callback

5014–5401 are VIDA backend errors returned during SDK processing. They appear in the errors[] array of the SDK response and are also surfaced via the onError(errorCode, errorMessage, response) callback on both Android and iOS.

Log these codes on your backend to identify patterns in document quality issues — e.g. high rates of 5202 may indicate a lighting problem in a specific geographic region.

SDK-Level Error Codes (Mobile Only)

These codes appear in the onError() callback of the mobile SDK. They are NOT returned by VIDA's backend APIs. If your app forwards error codes to your backend, use this table to interpret them.

Code Range	Platform	Category	Examples
42001–42013	Android & iOS	Network / HTTP errors	42001: Network timeout, 42008: HTTP 401 Unauthorized, 42011: HTTP 500
52001–52007	Android & iOS	SDK parsing / config errors	52001: Empty server response, 52004: Invalid input configuration, 52005: Detection timed out
72001–72050	iOS only	Device / runtime errors	72001: Back button pressed, 72005: Camera permission denied, 72008: Potential threat detected, 72012: Landscape not supported

For full SDK error code details

See the VIDA Android SDK Integration Guide and VIDA iOS SDK Integration Guide for the complete list of SDK error codes and recommended handling per code.

SDK error codes are never returned by VIDA backend APIs - they only surface in the mobile onError() callback.

overallStatus - Quick Diagnostic

Use this table to quickly diagnose what a given overallStatus means and where to look for more details.

overallStatus	First Place to Check	Common Cause
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