> ## 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 검증 및 에러 처리

> Face Auth URL 방식에서 발생하는 QueryString 검증 실패, 사전 로드 실패, 인증 처리 실패의 에러 코드와 사용자에게 실제로 노출되는 문구를 단계별로 정리했습니다.

<Info>
  이 문서는 **A. Face Auth URL 방식**([FaceAuth 시작하기](/ko/idcheck/add-on/faceauth-overview) 참고)에서 발생하는 실패를 다룹니다.

  **B. POST /faceauth API 방식**의 실패 코드·에러 코드는 [POST/Faceauth](/ko/idcheck/add-on/post-faceauth#6-오류-코드)를 참고하세요. 두 방식은 검증 파이프라인이 달라 노출되는 코드와 처리 방식도 다릅니다.
</Info>

## 1. 실패가 발생하는 3단계

Face Auth URL 방식은 실패 지점에 따라 사용자에게 보이는 화면이 달라집니다.

<Steps>
  <Step title="진입 — QueryString · 토큰 검증">
    URL의 `pid`, 암호화된 `sid`, `token`을 검증합니다. 실패하면 **에러 페이지로 이동**하며 인증이 시작되지 않습니다. → [2. 진입 단계 검증 실패](#2-진입-단계-검증-실패)
  </Step>

  <Step title="사전 로드 — 프로젝트 · 제출 건 조회">
    FaceAuth 프로젝트 옵션과 참조할 ID Check 제출 건을 조회합니다. 실패하면 **에러 페이지로 이동**합니다. → [3. 사전 로드 단계 서버 오류](#3-사전-로드-단계-서버-오류)
  </Step>

  <Step title="인증 처리 — 셀피 촬영 후 판정">
    촬영한 셀피로 얼굴 비교·라이브니스·가림 검증을 수행합니다. 실패 유형에 따라 **AlertPopup** 또는 **거절 결과 화면**이 표시됩니다. → [4. 인증 처리 단계 사용자 노출 문구](#4-인증-처리-단계-사용자-노출-문구)
  </Step>
</Steps>

## 2. 진입 단계 검증 실패

### 2-1. 필수 파라미터 누락

**Face Auth는 쿼리 스트링 없이 실행되지 않습니다.** `pid`만 붙인 URL로는 인증이 시작되지 않으며, 참조할 `sid`를 암호화해 `encrypted`에 담아야 최소 실행 조건이 충족됩니다.

| 에러 코드      | URL                                | 사용자 메시지 (KO)                                                                       | 발생 조건                                           |
| ---------- | ---------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| `PV-40015` | `/error-page/missing-faceauth-pid` | "인증 정보가 누락되었습니다"<br />얼굴 인증에 필요한 필수 파라미터(pid 또는 sid)가 없습니다. 올바른 링크를 통해 다시 접근해 주세요. | Face Auth 진입 시 `pid` 또는 복호화된 `sid` 중 하나라도 없는 경우 |

<Warning>
  `sid`는 **반드시 `encrypted` 내부에 포함**되어야 합니다. 평문 `sid`는 인식되지 않아 `PV-40015`로 처리됩니다. 암호화 방법은 [쿼리 스트링 암호화](/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-쿼리-스트링-암호화)를 참고하세요.
</Warning>

<Note>
  **`encrypted` 값이 잘못된 경우, 위 오류 코드 페이지가 아니라 "페이지를 찾을 수 없습니다" 화면이 표시될 수 있습니다.**

  실제 사례(2026-08): `pid`와 URL 인코딩은 모두 정상이었으나 **암호화 대상 평문을 쿼리 스트링 형식**(`sid=...&authUserId=...`)으로 만든 URL에서, `PV-40015` 오류 페이지로 이동하지 않고 `/face-auth` 경로에 머문 채 "페이지를 찾을 수 없습니다"가 표시되었습니다. 평문을 JSON 문자열로 바꾸자 정상 동작했습니다.

  인증 화면이 뜨지 않으면 아래 순서로 확인하세요.

  1. **평문 형식** — 암호화 대상은 **JSON 문자열**입니다(예: `{"sid":"..."}`). `key=value`를 `&`로 이어붙인 문자열을 암호화하면 복호화는 성공해도 `sid`를 찾지 못합니다.
  2. **URL 인코딩** — 암호화 결과(Base64)에 포함된 `+`가 URL에서 공백으로 해석되면 복호화 단계에서 실패합니다. `encodeURIComponent`를 적용하세요.
  3. **`sid` 상태** — 참조하는 eKYC 제출 건이 `approved` 상태인지 확인하세요.

  상세 예시는 [FaceAuth 시작하기 — FaceAuth에 접근하기 위한 QueryString](/ko/idcheck/add-on/faceauth-overview#faceauth에-접근하기-위한-querystring)에 있습니다.
</Note>

### 2-2. 토큰 검증 실패

FaceAuth 프로젝트에서 토큰 만료 조건 설정을 활성화한 경우, `token` 검증 실패 시 `TK-` 계열 에러 페이지로 이동합니다. 코드(`TK-10000` \~ `TK-10004`)와 문구는 [에러 코드와 에러 페이지](/ko/idcheck/reference_tables/Error-codes-and-pages)의 토큰 에러 페이지 항목에서 확인하세요.

<Note>
  FaceAuth의 `token`은 **메인 프로젝트(ID Check)의 프라이빗 모드 토큰·사전등록 토큰과 별개**로 동작하며, 토큰 DB와 만료 파이프라인이 분리되어 있습니다. 동작 방식은 [FaceAuth 시작하기 — 요청 파라미터들에 대한 정의](/ko/idcheck/add-on/faceauth-overview#요청-파라미터들에-대한-정의), 대시보드 설정은 [FACE AUTH 가이드 — 토큰 만료 조건 설정](/dashboard/ko/face-auth-guide#토큰-만료-조건-설정)을 참고하세요.
</Note>

## 3. 사전 로드 단계 서버 오류

프로젝트 옵션과 참조 제출 건을 조회하는 과정에서 발생하는 서버 오류입니다. 모두 `SE-` 계열이며, 사용자에게는 재시도 안내가 표시됩니다.

| 에러 코드      | URL                                     | 사용자 메시지 (KO)                                                                        | 발생 조건                                                      |
| ---------- | --------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `SE-50010` | `/error-page/faceauth-preload-error`    | "얼굴 인증 초기화에 실패했습니다"<br />얼굴 인증 준비 중 서버 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.                 | 사전 데이터를 로드하는 **첫 번째** API 쿼리 실패                            |
| `SE-50011` | `/error-page/faceauth-preload-error-2`  | "얼굴 인증 초기화에 실패했습니다"<br />얼굴 인증 추가 데이터 로드 중 서버 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.          | 사전 데이터를 로드하는 **두 번째** API 쿼리 실패                            |
| `SE-50012` | `/error-page/faceauth-submission-error` | "얼굴 인증 상태 확인에 실패했습니다"<br />인증 제출 상태를 확인하는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.            | `checkSubmission` API는 응답했으나 `result` 값이 유효하지 않은(falsy) 경우 |
| `SE-50013` | `/error-page/faceauth-token-error`      | "얼굴 인증 토큰 처리에 실패했습니다"<br />인증 토큰을 등록하는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.               | `insertToken` API 호출 중 예외 발생                               |
| `SE-50014` | `/error-page/faceauth-project-error`    | "얼굴 인증 프로젝트 정보를 불러올 수 없습니다"<br />서버에서 프로젝트 데이터를 가져오는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | FaceAuth 프로젝트 데이터 조회 API 호출 실패                             |

<Tip>
  Face Auth는 **승인(`approved`) 상태의 ID Check 제출 건만 참조할 수 있습니다.** 사전 로드 API는 제출 건의 유효성을 `result: true/false`로 반환하므로, 미승인 `sid`도 `SE-50012` 경로로 처리될 수 있습니다(동작상 추론). 링크 발급 전에 `sid`의 KYC 상태를 확인하세요.
</Tip>

## 4. 인증 처리 단계 사용자 노출 문구

셀피 촬영 후 인증 API 호출 결과에 따라 두 가지로 분기합니다.

### 4-1. HTTP StatusCode가 200이 아닌 경우 (비정상 처리)

원인을 구분하지 않고 **단일 문구로 통일**하여 **AlertPopup** 형식으로 표시합니다.

| 메시지 키             | 사용자 메시지 (KO)                        |
| ----------------- | ----------------------------------- |
| `SomethingsWrong` | 요청사항을 처리하는데 실패했습니다.<br />다시 시도해주세요. |

<Note>
  원문 문자열은 개행 문자를 포함합니다: `"요청사항을 처리하는데 실패했습니다.\n다시 시도해주세요."`

  내부 에러 코드는 사용자에게 노출되지 않습니다. 원인 파악은 웹훅 또는 [GET/FaceAuth](/ko/idcheck/add-on/get-faceauth) 응답으로 하세요.
</Note>

### 4-2. HTTP StatusCode가 200이지만 정상 처리되지 못한 경우 (거절)

`auth_status`가 `rejected`로 반환되며, `fail_code`에 따라 아래 문구가 표시됩니다.

| `fail_code`               | 사용자 메시지 (KO)        | 검증 항목                   |
| ------------------------- | ------------------- | ----------------------- |
| `no_face`                 | 얼굴 인식에 실패하였습니다.     | 얼굴 감지                   |
| `face_compare_underscore` | 제출하신 정보가 일치하지 않습니다. | 얼굴 유사도 임계치 미달           |
| `face_compare_fail`       | 얼굴 인식에 실패하였습니다.     | 얼굴 비교 진행 불가             |
| `Face_Occluded_fail`      | 얼굴이 가려졌습니다.         | 얼굴 가림 임계치 초과            |
| `Face_cover_fail`         | 마스크를 착용해주세요.        | 얼굴 보호장비(PPE) 미착용        |
| `Head_cover_fail`         | 보호모를 착용해주세요.        | 머리 보호장비(PPE) 미착용        |
| `active_liveness_fail`    | 얼굴 인증에 실패하였습니다.     | Active Liveness 임계치 미달  |
| `passive_liveness_fail`   | 얼굴 인증에 실패하였습니다.     | Passive Liveness 임계치 미달 |

<Note>
  `no_face`와 `face_compare_fail`이 같은 문구를 공유하며, `active_liveness_fail`과 `passive_liveness_fail`도 동일합니다. 어떤 검증이 실패했는지는 문구가 아니라 `fail_code`로 판별하세요.
</Note>

<Warning>
  **코드 표기 주의**

  * `fail_code` 값은 **대소문자를 구분**합니다. `Face_Occluded_fail`, `Face_cover_fail`, `Head_cover_fail`은 첫 글자가 대문자이고, 나머지는 모두 소문자입니다.
  * 라이브니스 실패 코드는 Face Auth에서 **`active_liveness_fail`**(Active) / **`passive_liveness_fail`**(Passive) 입니다. [거절 코드와 코멘트](/ko/idcheck/reference_tables/reject-codes-and-comments)의 `liveness_fail_active`·`liveness_fail`은 ID Check 본 프로세스의 재시도 코드로, 별개 값입니다.
</Warning>

<Note>
  위 표는 **사용자 화면에 노출되는 문구**입니다. API 응답과 웹훅으로 전달되는 `rejected_comment` 원문(예: `face compare similarity score is lower than threshold`)은 별도 값이며, [POST/Faceauth — 실패 코드](/ko/idcheck/add-on/post-faceauth#6-1-실패-코드)에서 확인하세요.
</Note>

### 4-3. 라이브니스 실패 코드

라이브니스 검증은 프로젝트 정책의 `livenessMode`(`passive` / `active`) 설정에 따라 실행되며, 실패 시 아래 코드가 반환됩니다.

| `fail_code`             | `rejected_comment`                    | 검증 항목                   |
| ----------------------- | ------------------------------------- | ----------------------- |
| `active_liveness_fail`  | Please retry with another face image. | Active Liveness 임계치 미달  |
| `passive_liveness_fail` | Please retry with another face image. | Passive Liveness 임계치 미달 |

<Note>
  `rejected_comment`는 API 응답과 웹훅으로 전달되는 값입니다. 두 코드의 코멘트 문구는 동일하므로, 어느 라이브니스가 실패했는지는 `fail_code`로 구분하세요.
</Note>

## 5. 재시도 정책

<Warning>
  **Face Auth는 재시도가 없습니다.** 1회 실패 시 즉시 거절 처리되며, ID Check·Knowledge-Based와 달리 `too_many_retry` 거절 코드가 발생하지 않습니다.

  ID Document(3회) / Knowledge-Based(5회)와의 비교는 [거절 코드와 코멘트 — 재시도 코드](/ko/idcheck/reference_tables/reject-codes-and-comments#재시도-코드)를 참고하세요.
</Warning>

## 6. 관련 문서

<CardGroup cols={2}>
  <Card title="FaceAuth 시작하기" icon="link" href="/ko/idcheck/add-on/faceauth-overview">
    Face Auth URL 구조와 QueryString 파라미터 정의
  </Card>

  <Card title="POST/Faceauth" icon="code" href="/ko/idcheck/add-on/post-faceauth">
    API 방식의 실패 코드 및 에러 코드
  </Card>

  <Card title="에러 코드와 에러 페이지" icon="triangle-exclamation" href="/ko/idcheck/reference_tables/Error-codes-and-pages">
    전체 에러 코드 체계 및 에러 페이지 정의
  </Card>

  <Card title="FACE AUTH 가이드" icon="gauge" href="/dashboard/ko/face-auth-guide">
    대시보드 정책·임계값·토큰 만료 설정
  </Card>
</CardGroup>