Errors and diagnostics

The codes, at a glance

Code	Emitted by	What it means	What to do
`200`	Service	The operation ran. It does not imply a match or good quality: evaluate `biometric` and `inferenceConfidence`.	Apply the decision rule.
`400`	Service	A problem with a specific image or operation: no face, too small, invalid base64, nonexistent operation.	Fix the indicated image or operation. Do not retry as-is.
`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 /inference` returns 404, not 405).	Check route and method.
`422`	Service	The body is not valid JSON, is not an object, or `info` violates its format.	Fix the body.
`500`	Service	Either a transient error, or your request: `images` missing or `operations` misaligned. Plain-text body.	See the 500 section.

The `400`s: a single error, with an index

The 400 body points at the offending image with imageNumber (0-based):

{
  "id": "7be2f9a1-...",
  "code": 400,
  "message": "Face not found",
  "imageNumber": 1
}

Message	Cause
`Face not found`	No face was detected in the indicated image. Ask for another capture.
`Image is too small`	The image is below the hard minimum of 160 × 160 px.
`Image is not valid`	The content of `images[i]` is not decodable base64.
`Operation is not valid`	An operation name does not exist, or you sent `operations` as a flat list instead of a list of lists.

One bad image aborts the whole batch. If you send 4 images and the third has no face, you get a single 400 with imageNumber: 2 and no results — there are no partial results. If your flow tolerates per-image failures, send one request per image.

The `500`s come as plain text

Two request errors do not return a tidy 400 but a 500 whose body is the literal string Internal Server Error — not JSON:

Omitting the images field.
Sending an operations list shorter than images.

Your HTTP client must not assume every response is JSON: wrap the parsing and treat a parse failure as an error, never as an approval. How to tell a transient 500 from one of yours: retry it once with backoff. If it comes back identical, it is deterministic — your request causes it; validate images and the operations alignment in your code and stop retrying.

The gateway errors: another format

The 401 and 404 are not emitted by the service but by the gateway, and their body has another format (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"
}

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 `422`s: contract violations

A non-JSON body, a body that is not an object, or an info out of range (2–256 characters) return 422 with a per-field breakdown in detail. These are programming errors, not data errors: fix them in development, do not handle them in production.

Retry policy

Error	Retry?
Sporadic `500` (does not repeat identically)	Yes, with backoff, maximum 2.
Deterministic `500`	No: fix the request.
`400` / `401` / `404` / `422`	No: fix the image, credential, route or body.
No-match (`200` with a low score)	Never with the same image: the result is deterministic. Ask for another capture.
`spoofing: true`	Never with the same image.

If you have to open a ticket

Write to customer.support@vusecurity.com with:

Data	Where it is
The transaction `id`	In the response body (also present in the `400`s).
The environment	UAT or production.
Approximate date and time	With timezone.
The HTTP code and message	Without attaching base64 images or raw bodies containing personal data.

Back to the introduction

The decision rule, the endpoints and the operation map of Face Analysis.

Start here

ID Analysis

Face Analysis

Facial Antispoofing

Connection Fingerprint

The codes, at a glance

The `400`s: a single error, with an index

The `500`s come as plain text

The gateway errors: another format

The `422`s: contract violations

Retry policy

If you have to open a ticket

Back to the introduction

​The codes, at a glance

​The 400s: a single error, with an index

​The 500s come as plain text

​The gateway errors: another format

​The 422s: contract violations

​Retry policy

​If you have to open a ticket

Back to the introduction

The codes, at a glance

The `400`s: a single error, with an index

The `500`s come as plain text

The gateway errors: another format

The `422`s: contract violations

Retry policy

If you have to open a ticket