> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/kyc-web-sdk/integration/backend-integration/error-code.md).

# 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](https://app.gitbook.com/o/HFo4Mq4hPbfFvhTREpfY/s/zqikP7fR7hLesltIaRUc/integration-methods/api/document-ai/ocr-and-document-verification-v2/http-status-and-error-codes)

## KYC Error Codes

<table><thead><tr><th width="96.3984375">Code</th><th>Name</th><th width="96.35546875">HTTP</th><th width="150.80078125">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>5701</td><td>TRANSACTION_NOT_FOUND_ERROR</td><td>404</td><td><code>GET</code> <code>/transaction</code> <code>GET</code> <code>/status</code></td><td>Audit store has no row for the provided transactionId.</td></tr><tr><td>5702</td><td>KYC_FLOW_TERMINAL_ERROR</td><td>400</td><td><code>POST</code> <code>/verify</code></td><td>The KYC case is already in a terminal state (<code>VERIFIED</code> or <code>FAILED</code>). No further operations accepted. New requests using this groupId will be rejected.</td></tr><tr><td>5703</td><td>NO_VALID_LIVENESS_TRANSACTION_FOUND</td><td>400</td><td><code>POST</code> <code>/verify</code></td><td>No valid liveness image was found for the supplied livenessTransactionIds during <code>IMAGE_FACEMATCH_VERIFICATION</code>.</td></tr><tr><td>5704</td><td>TRANSACTION_RESPONSE_NOT_AVAILABLE</td><td>404</td><td><p><code>GET</code> <code>/transaction</code></p><p><code>GET</code> <code>/status</code></p></td><td>Audit row exists but the stored response payload is blank.</td></tr><tr><td>5705</td><td>DOCUMENT_NOT_FOUND</td><td>404</td><td><p><code>GET</code> <code>/transaction</code></p><p><code>GET</code> <code>/status</code></p></td><td>A presigned URL for the document image could not be generated - document not found in storage.</td></tr></tbody></table>

{% hint style="info" %}
**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.
{% endhint %}

## Warning Code

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

<table><thead><tr><th width="130.30078125">Code</th><th>Description</th><th>How to Handle</th></tr></thead><tbody><tr><td>10014</td><td>Image occlusion detected - a landmark element on the ID card is partially or fully covered</td><td>Check <code>landmarkResult.containerResult</code> for the element with score: 0 to identify which landmark is occluded. No action required to continue.</td></tr></tbody></table>

## Face Match Result Codes

<table><thead><tr><th width="130.1171875">Code</th><th>Message</th><th>Meaning</th></tr></thead><tbody><tr><td>1042</td><td>Selfie photo matches with reference photo</td><td>Face match passed - selfie matches ID portrait</td></tr><tr><td>1040</td><td>Selfie photo does not match reference photo</td><td>Face match failed - selfie does not match ID portrait</td></tr><tr><td>1041</td><td>Photo liveness score is below the threshold</td><td>Liveness check failed - the image did not pass the liveness threshold</td></tr></tbody></table>

### Liveness Fraud Codes

<table><thead><tr><th width="129.890625">Code</th><th>Source</th><th>Meaning</th></tr></thead><tbody><tr><td>1705</td><td>Liveness Service API response</td><td>VIDA fraud threshold breached during liveness check. Returned in the errors array of the Liveness Service <code>GET</code> transaction response.</td></tr><tr><td>10001</td><td>Liveness Service DB state</td><td>Transaction marked as <code>FAILURE</code> due to fraud detection. When My-Verify fetches this liveness transaction, the real liveness scores are hidden and only the fraud error is returned.</td></tr></tbody></table>

## 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.

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

{% hint style="info" %}
**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.
{% endhint %}

## 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 |

{% hint style="info" %}
**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.
{% endhint %}

## 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 |