Error Codes

Every Vlens response uses the same envelope. Errors are signalled by the error_code field — not the HTTP status. A 200 OK response with error_code set is still an error.

1
{
2
  "data": null,
3
  "error_code": 3011,
4
  "error_message": "Card Not Detected",
5
  "error_descriptions": null
6
}

Handling errors

Always check error_code before treating a response as successful:

1
const res = await fetch(url, options);
2
const body = await res.json();
3
4
if (body.error_code !== null) {
5
  throw new VlensError(body.error_code, body.error_message);
6
}
7
8
return body.data;

HTTP Error Codes

VLens Error Codes

Document Validation (3xxx)

Bundle & Quota (4xxx)

General & Document Errors (5xxx)

Identity & Contract Errors (6xxx)

Card & OCR Service Errors (7xxx)

Retry strategy

1
async function callVlensWithRetry(fn, maxAttempts = 3) {
2
  let delay = 500;
3
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
4
    try {
5
      return await fn();
6
    } catch (err) {
7
      // Only retry transient errors — never retry validation or auth failures
8
      if (!isTransient(err) || attempt === maxAttempts) throw err;
9
      await new Promise(r => setTimeout(r, delay));
10
      delay = Math.min(delay * 2, 8000);
11
    }
12
  }
13
}

Helpful Tips

Validation errors

When request fields fail validation, the response may include structured field-level details in error_descriptions:

1
{
2
  "data": null,
3
  "error_code": 400,
4
  "error_message": "Validation failed",
5
  "error_descriptions": [
6
    { "field": "image", "message": "image is required" }
7
  ]
8
}

Iterate error_descriptions to surface field-level errors in your UI.

Getting help

If you encounter an error not listed here, contact support@vlenseg.com with:

1. The endpoint URL and method
2. The full request body (redact images and PII)
3. The full response body including error_code and error_message
4. Your tenant name and approximate UTC timestamp