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

> ID Analysis error codes, the 422 that echoes your whole request, the gateway's 401/404 format, and which errors are safe to retry.

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

```json theme={null}
{
  "uuid": "0f3f4a51-...",
  "code": 400,
  "message": "No document detected"
}
```

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

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

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

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

## The gateway errors: another format

The `401` and `404` come from the gateway, with `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"
  }
  ```

  ```json 404 unknown template theme={null}
  {
    "code": 404,
    "message": "Template 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 `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**](mailto: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. |

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

<Card title="Back to the introduction" icon="id-card" href="/en/vucs/id-analysis/introduction">
  The decision rule, the three identifiers and the endpoint map of ID Analysis.
</Card>


## Related topics

- [Errors and diagnostics](/en/vucs/face-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.