> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and diagnostics

> Face Analysis error codes, the 500s with plain-text bodies, the batch abort with imageNumber, and which errors are safe to retry.

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

```json theme={null}
{
  "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. |

<Warning>
  **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.
</Warning>

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

1. Omitting the `images` field.
2. 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`):

<CodeGroup>
  ```json 401 missing Api-Key theme={null}
  {
    "statusCode": 401,
    "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
  }
  ```

  ```json 401 invalid api-key theme={null}
  {
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
  }
  ```

  ```json 404 route or method theme={null}
  {
    "statusCode": 404,
    "message": "Resource not found"
  }
  ```
</CodeGroup>

<Note>
  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.
</Note>

## 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**](mailto: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. |

<Card title="Back to the introduction" icon="user-check" href="/en/vucs/face-analysis/introduction">
  The decision rule, the endpoints and the operation map of Face Analysis.
</Card>


## Related topics

- [Errors and diagnostics](/en/vucs/id-analysis/errors.md)
- [Reading the response](/en/vucs/antispoofing-face/responses.md)
- [Facial Antispoofing](/en/vucs/antispoofing-face/introduction.md)
- [Integration guide](/en/vucs/face-analysis/integration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.