HTTP Status and Error Codes

The APIs utilize HTTPS response codes to indicate the outcome of an API request, signaling either success or failure. In addition to these standard codes, VIDA also provides internal custom codes that are specifically designed to identify and categorize any encountered errors.

Error Codes

The below tables offers a clear overview of the various error codes, their corresponding HTTP status codes, and the associated error messages. This can be particularly useful for developers for debugging and error handling.

Note: For detailed examples of different scenarios please refer to the below pages:

OCR+IDV : All Error Scenarios Related to OCR and IDV

Also each error code mentioned in the table is already linked to the appropriate example in the page above.

Generic Code for MyKad, NonMyKad, Passport and KTP cards

Note: The messages mentioned in the below table's may vary depending on validation checks, flow errors, and other conditions. This message is intended to provide a general idea of what the error code represents. Sample messages can be found on the referenced page above. Please do not use the error messages for the processing of the requests instead rely on the error codes.

Error Code	HTTP Status Code	Message
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.
5008	500	Data processing error.
5009	400	Wrong input format
5010	400	Invalid Image Specification
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.
5023	400	Bad Quality Image , Id Number Extraction Failed
5024	400	The given card is forged
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.
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.
5101	400	No card detected
5102	500	Error processing input/output
5104	400	Minimum OCR fields did not meet the score threshold
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 (400x300), the recommended image size is (800x600))
5302	400	Card resolution is larger than (4000x3000), the recommended image size is (800x600))
5303	400	Image size is larger than max allowed 3MB
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. Send the front side image first.
5401	400	Orientation unknown, take image of card on a flat surface in upright position
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
5404	400	The submitted document type is not supported for automated verification

Invalid or expired products or product-related issues

Error Code	Http Status Code	Message
5502	400	[OSS] Product credentials not found
5503	400	[OSS] Product expired
5504	400	[OSS] Invalid License
5505	400	Invalid product
5506	400	[OSS] Product id not found

Spoof Code for Error Card

Error Code	Http Status Code	Message
5028	400	The card appears to be spoofed.
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
5612	400	Card edges are not fully visible. Please re-capture the card with all four edges within the frame.
5613	400	Landmark positions are not in correct arrangement

OCR Error Code

Error Code	Http Status Code	Message
5027	400	The ID numbers on the front and back of your card do not match. Please upload both sides of the same card.
5103	400	Bad Quality Image , Portrait Extraction Failed

Specific Code for Non-Malaysian & NonKTP cards

Error Code	Http Status Code	Message
5005	500	extraction_failed

NFC Error Code

Error Code	HTTP Status Code	Message
5621	400	Passive authentication failed
5622	400	Active authentication failed
5623	400	Chip authentication failed
5624	400	NFC verification 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. Contact support.

Transaction Error Code

These error codes are returned by the transaction-related endpoints. They fall into two groups based on the endpoint you call.

1. GET /transaction and GET /status (codes 5701, 5704, 5705): These codes apply only to the GET /transaction and GET /status endpoints. A standard integration that does not call these endpoints will never receive codes 5701, 5704, or 5705.

2. POST /verify (codes 5702, 5703): These codes apply to the POST /verify endpoint. The POST /verify endpoint is part of the verification flow, so any integration can receive them.

Error Code	Http Status Code	Message	Applicable (Endpoints)
5701	404	Transaction not found for the given transactionId.	GET /transaction GET /status
5702	400	The KYC flow for this transaction has already reached a terminal state. No further verification requests can be processed.	POST /verify
5703	400	No valid liveness transaction found for the provided livenessTransactionIds.	POST /verify
5704	404	Transaction response is not available for the given transactionId.	GET /transaction GET /status
5705	404	Document not found for given transaction.	GET /transaction GET /status

Note: Error 5703 is validated during the IMAGE_FACEMATCH_VERIFICATION stage. Error 5702 indicates the KYC case has already reached a final state (completed or rejected) — a new transaction must be initiated to perform further verification. This section replaces the previous “Pre-signed URL Error Code” section; error 5705 is unchanged and now documented here.

Deduplication Error Code

Error Code	Http Status Code	Message
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

Warning Codes

OCR Codes

Warning Code	HTTP status code	Message
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
10108	200	Low confidence score for ocr, please check [province] from ocrResult for more details
10109	200	Low confidence score for ocr, please check [city] from ocrResult for more details
10110	200	Low confidence score for ocr, please check [placeOfBirth] from ocrResult for more details
10111	200	Low confidence score for ocr, please check [bloodType] from ocrResult for more details
10112	200	Low confidence score for ocr, please check [neighborhoodAssociationGroup] from ocrResult for more details
10113	200	Low confidence score for ocr, please check [village] from ocrResult for more details
10114	200	Low confidence score for ocr, please check [subDistrict] from ocrResult for more details
10115	200	Low confidence score for ocr, please check [maritalStatus] from ocrResult for more details
10116	200	Low confidence score for ocr, please check [occupation] from ocrResult for more details
10117	200	Low confidence score for ocr, please check [nationality] from ocrResult for more details
10118	200	Low confidence score for ocr, please check [validUntil] 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
10130	200	Low confidence score for ocr, please check [address1] from for more details
10131	200	Low confidence score for ocr, please check [address2] from for more details
10132	200	Low confidence score for ocr, please check [zipCode] from ocrResult for more details
10133	200	Low confidence score for ocr, please check [state] from ocrResult for more details

Landmark Codes

Warning Code	HTTP status code	Message
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.
10411	200	Image has Occlusion, please check [provinsi] from landmarkResult for more details
10412	200	Image has Occlusion, please check [nik] from landmarkResult for more details
10413	200	Image has Occlusion, please check [nama] from landmarkResult for more details
10414	200	Image has Occlusion, please check [tampat-tgl-lahir] from landmarkResult for more details
10415	200	Image has Occlusion, please check [jenis-kelamin] from landmarkResult for more details
10416	200	Image has Occlusion, please check [alamat] from landmarkResult for more details
10417	200	Image has Occlusion, please check [rt-rw] from landmarkResult for more details
10418	200	Image has Occlusion, please check [kel-desa] from landmarkResult for more details
10419	200	Image has Occlusion, please check [kecamatan] from landmarkResult for more details
10420	200	Image has Occlusion, please check [agama] from landmarkResult for more details
10421	200	Image has Occlusion, please check [status-perkawinan] from landmarkResult for more details
10422	200	Image has Occlusion, please check [pekerjaan] from landmarkResult for more details
10423	200	Image has Occlusion, please check [kewarganegaraan] from landmarkResult for more details
10424	200	Image has Occlusion, please check [berlaku-hingga] from landmarkResult for more details
10425	200	Image has Occlusion, please check [gol-darah] from landmarkResult for more details
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
10434	200	Card edges may not be fully visible. Please re-capture the card with all four edges within the frame.
10435	200	Image has Occlusion, please check [signature] from landmark Result for more details
10436	200	Landmark positions are not in correct arrangement

Deduplication Warning Code

Error Code	HTTP Status Code	Operation	Description
10502	200	Operation.OCR	Face from card associated with multiple ID Numbers.
10503	200	Operation.OCR	ID Number from card associated with multiple faces.

NFC Warning Code

Error Code	HTTP Status Code	Description
10520	200	Data discrepancy detected between chip and document image
10521	200	Portrait mismatch detected between chip and document image