Skip to main content
This page covers failures in the A. Face Auth URL flow (see FaceAuth Getting Started).For the failure codes and error codes of the B. POST /faceauth API flow, see POST/Faceauth. The two flows use different verification pipelines, so the codes they return and the way failures are handled differ.

​
1. Three stages where failures occur

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

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

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

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

​
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.
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.
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.

​
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.
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, and for the dashboard setting see FACE AUTH Guide — Token Expiration Condition Settings.

​
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.
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.

​
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.
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 response.

​
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.
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.
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 are retry codes for the main ID Check process — separate values.
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.

​
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.
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.

​
5. Retry policy

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.

FaceAuth Getting Started

Face Auth URL structure and QueryString parameter definitions

POST/Faceauth

Failure codes and error codes for the API flow

Error Codes and Error Pages

Full error code taxonomy and error page definitions

FACE AUTH Guide

Dashboard policy, thresholds, and token expiration settings