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

# Face Auth URL Validation and Error Handling

> A stage-by-stage reference for the Face Auth URL flow: QueryString validation failures, pre-load failures, and authentication failures, along with the messages users actually see.

<Info>
  This page covers failures in the **A. Face Auth URL** flow (see [FaceAuth Getting Started](/en/idcheck/add-on/faceauth-overview)).

  For the failure codes and error codes of the **B. POST /faceauth API** flow, see [POST/Faceauth](/en/idcheck/add-on/post-faceauth#6-error-codes). The two flows use different verification pipelines, so the codes they return and the way failures are handled differ.
</Info>

## 1. Three stages where failures occur

In the Face Auth URL flow, the screen the user sees depends on where the failure happens.

<Steps>
  <Step title="Entry — QueryString and token validation">
    Validates `pid`, the encrypted `sid`, and `token` in the URL. On failure the user is **redirected to an error page** and verification never starts. → [2. Entry stage validation failures](#2-entry-stage-validation-failures)
  </Step>

  <Step title="Pre-load — project and submission lookup">
    Retrieves the FaceAuth project options and the referenced ID Check submission. On failure the user is **redirected to an error page**. → [3. Pre-load stage server errors](#3-pre-load-stage-server-errors)
  </Step>

  <Step title="Authentication — judgment after the selfie capture">
    Runs face comparison, liveness, and occlusion checks on the captured selfie. Depending on the failure type, either an **AlertPopup** or a **rejection result screen** is shown. → [4. Authentication stage user-facing messages](#4-authentication-stage-user-facing-messages)
  </Step>
</Steps>

## 2. Entry stage validation failures

### 2-1. Missing required parameters

**Face Auth does not run without a query string.** A URL carrying only `pid` will not start verification; the minimum runnable form requires the `sid` to reference, encrypted and passed inside `encrypted`.

| Error Code | URL                                | User Message                                                                                                                                                 | Trigger                                                                 |
| ---------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| `PV-40015` | `/error-page/missing-faceauth-pid` | "Authentication information is missing"<br />Required parameters (pid or sid) for face authentication are missing. Please access again via the correct link. | Entering the Face Auth flow without `pid` or without a decrypted `sid`. |

<Warning>
  `sid` **must be included inside `encrypted`**. A plaintext `sid` is not recognized and results in `PV-40015`. For the encryption procedure, see [Query String Encryption](/en/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-query-string-encryption).
</Warning>

<Note>
  **A malformed `encrypted` value may render a "Page not found" screen instead of the error-code page above.**

  Observed case (2026-08): `pid` and URL encoding were both correct, but the **plaintext had been built as a query string** (`sid=...&authUserId=...`). The URL did not redirect to the `PV-40015` error page — it stayed on `/face-auth` and showed "Page not found". Switching the plaintext to a JSON string made it work.

  If the verification screen does not appear, check in this order.

  1. **Plaintext format** — what you encrypt is a **JSON string** (for example `{"sid":"..."}`). Encrypting `key=value` pairs joined with `&` decrypts fine but yields no `sid`.
  2. **URL encoding** — a `+` in the Base64 output decodes as a space in the URL, so decryption itself fails. Apply `encodeURIComponent`.
  3. **`sid` status** — confirm the referenced eKYC submission is `approved`.

  Detailed examples are in [FaceAuth Getting Started — QueryString for Accessing FaceAuth](/en/idcheck/add-on/faceauth-overview#querystring-for-accessing-faceauth).
</Note>

### 2-2. Token validation failures

If token expiration is enabled on the FaceAuth project, a failed `token` validation redirects to a `TK-` error page. For the codes (`TK-10000` – `TK-10004`) and their messages, see the token error page section of [Error Codes and Error Pages](/en/idcheck/reference_tables/Error-codes-and-pages).

<Note>
  The FaceAuth `token` operates **separately from the main ID Check project's private mode token and pre-registered token** — it uses its own token DB and expiration pipeline. For its behavior see [FaceAuth Getting Started — Definition of Request Parameters](/en/idcheck/add-on/faceauth-overview#definition-of-request-parameters), and for the dashboard setting see [FACE AUTH Guide — Token Expiration Condition Settings](/dashboard/en/face-auth-guide#token-expiration-condition-settings).
</Note>

## 3. Pre-load stage server errors

Server errors raised while retrieving project options and the referenced submission. All are `SE-` codes, and the user is prompted to retry.

| Error Code | URL                                     | User Message                                                                                                                                         | Trigger                                                   |
| ---------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `SE-50010` | `/error-page/faceauth-preload-error`    | "Face authentication initialization failed"<br />A server error occurred while preparing face authentication. Please try again later.                | The **first** API query for pre-loading data fails.       |
| `SE-50011` | `/error-page/faceauth-preload-error-2`  | "Face authentication initialization failed"<br />A server error occurred while loading additional face authentication data. Please try again later.  | The **second** API query for pre-loading data fails.      |
| `SE-50012` | `/error-page/faceauth-submission-error` | "Failed to verify face authentication status"<br />An error occurred while checking the authentication submission status. Please try again later.    | The `checkSubmission` API responds but `result` is falsy. |
| `SE-50013` | `/error-page/faceauth-token-error`      | "Face authentication token processing failed"<br />An error occurred while registering the authentication token. Please try again later.             | An exception occurs during the `insertToken` API call.    |
| `SE-50014` | `/error-page/faceauth-project-error`    | "Unable to load face authentication project information"<br />An error occurred while fetching project data from the server. Please try again later. | The API call to retrieve FaceAuth project data fails.     |

<Tip>
  Face Auth can only reference ID Check submissions in **`approved` status**. The pre-load API returns submission validity as `result: true/false`, so an unapproved `sid` is expected to surface through the `SE-50012` path (inferred from the pre-load contract). Verify the KYC status of `sid` before issuing the link.
</Tip>

## 4. Authentication stage user-facing messages

After the selfie is captured, the result of the authentication API call branches in two ways.

### 4-1. HTTP StatusCode is not 200 (abnormal processing)

All causes are collapsed into **a single message**, shown as an **AlertPopup**.

| Message Key       | User Message                                           |
| ----------------- | ------------------------------------------------------ |
| `SomethingsWrong` | Failed to process your request.<br />Please try again. |

<Note>
  The raw string contains a newline character: `"Failed to process your request.\nPlease try again."`

  Internal error codes are never exposed to the user. Diagnose the cause from the webhook or the [GET/FaceAuth](/en/idcheck/add-on/get-faceauth) response.
</Note>

### 4-2. HTTP StatusCode is 200 but processing did not succeed (rejected)

`auth_status` is returned as `rejected`, and the message shown depends on `fail_code`.

| `fail_code`               | User Message                                  | Verification Item                      |
| ------------------------- | --------------------------------------------- | -------------------------------------- |
| `no_face`                 | Face recognition failed.                      | Face detection                         |
| `face_compare_underscore` | The information you submitted does not match. | Face similarity below threshold        |
| `face_compare_fail`       | Face recognition failed.                      | Face comparison could not be performed |
| `Face_Occluded_fail`      | Your face is covered.                         | Face occlusion above threshold         |
| `Face_cover_fail`         | Please wear a mask.                           | Face PPE not detected                  |
| `Head_cover_fail`         | Please wear a safety helmet.                  | Head PPE not detected                  |
| `active_liveness_fail`    | Face authentication failed.                   | Active Liveness below threshold        |
| `passive_liveness_fail`   | Face authentication failed.                   | Passive Liveness below threshold       |

<Note>
  `no_face` and `face_compare_fail` share one message, as do `active_liveness_fail` and `passive_liveness_fail`. Use `fail_code` — not the message — to identify which check failed.
</Note>

<Warning>
  **Code notation**

  * `fail_code` values are **case-sensitive**. `Face_Occluded_fail`, `Face_cover_fail`, and `Head_cover_fail` start with an uppercase letter; all others are lowercase.
  * In Face Auth, the liveness failure codes are **`active_liveness_fail`** (Active) and **`passive_liveness_fail`** (Passive). The `liveness_fail_active` and `liveness_fail` values in [Rejected Codes and Comments](/en/idcheck/reference_tables/reject-codes-and-comments) are retry codes for the main ID Check process — separate values.
</Warning>

<Note>
  The table above lists the **messages shown on screen**. The `rejected_comment` strings delivered through the API response and webhooks (for example, `face compare similarity score is lower than threshold`) are separate values — see [POST/Faceauth — Failure Codes](/en/idcheck/add-on/post-faceauth#6-1-failure-codes).
</Note>

### 4-3. Liveness failure codes

Liveness verification runs according to the project policy's `livenessMode` setting (`passive` / `active`), and returns the following codes on failure.

| `fail_code`             | `rejected_comment`                    | Verification Item                |
| ----------------------- | ------------------------------------- | -------------------------------- |
| `active_liveness_fail`  | Please retry with another face image. | Active Liveness below threshold  |
| `passive_liveness_fail` | Please retry with another face image. | Passive Liveness below threshold |

<Note>
  `rejected_comment` is the value delivered through the API response and webhooks. Both codes share the same comment string, so use `fail_code` to determine which liveness check failed.
</Note>

## 5. Retry policy

<Warning>
  **Face Auth has no retries.** A single failure results in immediate rejection, and unlike ID Check and Knowledge-Based, the `too_many_retry` rejection code is never produced.

  For a comparison with ID Document (3 retries) and Knowledge-Based (5 retries), see [Rejected Codes and Comments — Retry Codes](/en/idcheck/reference_tables/reject-codes-and-comments#retry-codes).
</Warning>

## 6. Related documents

<CardGroup cols={2}>
  <Card title="FaceAuth Getting Started" icon="link" href="/en/idcheck/add-on/faceauth-overview">
    Face Auth URL structure and QueryString parameter definitions
  </Card>

  <Card title="POST/Faceauth" icon="code" href="/en/idcheck/add-on/post-faceauth">
    Failure codes and error codes for the API flow
  </Card>

  <Card title="Error Codes and Error Pages" icon="triangle-exclamation" href="/en/idcheck/reference_tables/Error-codes-and-pages">
    Full error code taxonomy and error page definitions
  </Card>

  <Card title="FACE AUTH Guide" icon="gauge" href="/dashboard/en/face-auth-guide">
    Dashboard policy, thresholds, and token expiration settings
  </Card>
</CardGroup>