Errors and diagnostics

The codes, at a glance

Code	Emitted by	What it means	What to do
`200`	Service	The analysis ran. Not an approval: check `message`, `id` and the back validations.	Apply the decision rule.
`400`	Service	A problem with the capture or the link: image too small, not decodable, no document detected, bad `relatedUuid`.	Fix the capture or the link.
`401`	Gateway	Missing `Api-Key` or a key that is not valid for this environment.	Check key and environment.
`404`	Gateway	Nonexistent route or wrong HTTP method (a `GET /front` returns 404, not 405). Also an unknown template id on the catalog.	Check route and method.
`422`	Service	Contract violation: missing `info`, missing `image`, malformed body. The error echoes your request.	Fix the body.
`500`	Service	A transient error — or a deterministic one caused by your request (`relatedUuid` on `/front`).	See the 500 section.
`503`	Service	The OCR engine is down.	Retry later with backoff.

The `400` messages

Message	Cause
`Image is too small ...`	Below 480 × 480 (the message reports height × width).
`Image is not a valid`	The base64 does not decode to an image.
`No document detected`	The capture has no recognizable document. Ask for another capture.
`relatedUuid or documentId is required`	`/back` without `relatedUuid`. The message is misleading: only `relatedUuid` links the transaction; `documentId` does not replace it.
`Bad relatedUuid`	The `relatedUuid` does not correspond to a registered front. If it happens immediately after a successful front, wait one second and retry once (replication lag); if it persists, the value is wrong.
`Document is too close to the borders`	With `strictBorderMode`: the document is cut off. Ask for another capture.

Error bodies look like this:

{
  "uuid": "0f3f4a51-...",
  "code": 400,
  "message": "No document detected"
}

The uuid in an error body is generated on the spot and does not correspond to any transaction — it is not usable as relatedUuid and support cannot look it up.

The 422 echoes your whole request — image included

The validation error’s detail[].input field is the literal echo of what you sent, base64 image included, so a 422 can weigh as much as the request itself:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "info"],
      "msg": "Field required",
      "input": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...v9Un0ooqDE//2Q==" }
    }
  ]
}

Never log raw error bodies. A logged 422 persists the document photo of a real person in your logs. Log the code, the message and the field path — never input.

The gateway errors: another format

The 401 and 404 come from the gateway, with statusCode instead of code:

{
  "statusCode": 401,
  "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

{
  "statusCode": 404,
  "message": "Resource not found"
}

{
  "code": 404,
  "message": "Template not found"
}

A 401 with a key that “always worked” is usually an environment mix-up: the UAT key against the production URL or vice versa. Verify the URL + key pair before escalating.

The `500`s

One 500 is deterministic and yours: sending relatedUuid in /front. It reproduces identically on every attempt — do not retry it; remove the field. Any other 500 is transient: retry with backoff, maximum 2 attempts. The determinism test is the same as always: if the retry returns the identical error, the cause is your request. healthCheck can return 408 while still answering "Service OK" on /version — treat it as a degradation warning, not an outage. A 503 means the OCR engine is down: nothing to fix on your side; retry later.

If you have to open a ticket

Write to customer.support@vusecurity.com with:

Data	Where it is
The transaction `uuid`	In the `200` body of `/front` (also in the `x-request-id` header).
The environment	UAT or production.
Approximate date and time	With timezone.
The HTTP code and message	Without the `detail` of a `422`, which contains the image.

Data protection: never attach document photos or raw response bodies to a ticket unless support explicitly asks for them through a secure channel.

Back to the introduction

The decision rule, the three identifiers and the endpoint map of ID Analysis.

Start here

ID Analysis

Face Analysis

Facial Antispoofing

Connection Fingerprint

The codes, at a glance

The `400` messages

The 422 echoes your whole request — image included

The gateway errors: another format

The `500`s

If you have to open a ticket

Back to the introduction

​The codes, at a glance

​The 400 messages

​The 422 echoes your whole request — image included

​The gateway errors: another format

​The 500s

​If you have to open a ticket

Back to the introduction

The codes, at a glance

The `400` messages

The 422 echoes your whole request — image included

The gateway errors: another format

The `500`s

If you have to open a ticket