이 문서는 A. Face Auth URL 방식(FaceAuth 시작하기 참고)에서 발생하는 실패를 다룹니다.B. POST /faceauth API 방식의 실패 코드·에러 코드는 POST/Faceauth를 참고하세요. 두 방식은 검증 파이프라인이 달라 노출되는 코드와 처리 방식도 다릅니다.
1. 실패가 발생하는 3단계
Face Auth URL 방식은 실패 지점에 따라 사용자에게 보이는 화면이 달라집니다.1
진입 — QueryString · 토큰 검증
URL의
pid, 암호화된 sid, token을 검증합니다. 실패하면 에러 페이지로 이동하며 인증이 시작되지 않습니다. → 2. 진입 단계 검증 실패2
사전 로드 — 프로젝트 · 제출 건 조회
FaceAuth 프로젝트 옵션과 참조할 ID Check 제출 건을 조회합니다. 실패하면 에러 페이지로 이동합니다. → 3. 사전 로드 단계 서버 오류
3
인증 처리 — 셀피 촬영 후 판정
촬영한 셀피로 얼굴 비교·라이브니스·가림 검증을 수행합니다. 실패 유형에 따라 AlertPopup 또는 거절 결과 화면이 표시됩니다. → 4. 인증 처리 단계 사용자 노출 문구
2. 진입 단계 검증 실패
2-1. 필수 파라미터 누락
Face Auth는 쿼리 스트링 없이 실행되지 않습니다.pid만 붙인 URL로는 인증이 시작되지 않으며, 참조할 sid를 암호화해 encrypted에 담아야 최소 실행 조건이 충족됩니다.
encrypted 값이 잘못된 경우, 위 오류 코드 페이지가 아니라 “페이지를 찾을 수 없습니다” 화면이 표시될 수 있습니다.실제 사례(2026-08): pid와 URL 인코딩은 모두 정상이었으나 암호화 대상 평문을 쿼리 스트링 형식(sid=...&authUserId=...)으로 만든 URL에서, PV-40015 오류 페이지로 이동하지 않고 /face-auth 경로에 머문 채 “페이지를 찾을 수 없습니다”가 표시되었습니다. 평문을 JSON 문자열로 바꾸자 정상 동작했습니다.인증 화면이 뜨지 않으면 아래 순서로 확인하세요.- 평문 형식 — 암호화 대상은 JSON 문자열입니다(예:
{"sid":"..."}).key=value를&로 이어붙인 문자열을 암호화하면 복호화는 성공해도sid를 찾지 못합니다. - URL 인코딩 — 암호화 결과(Base64)에 포함된
+가 URL에서 공백으로 해석되면 복호화 단계에서 실패합니다.encodeURIComponent를 적용하세요. sid상태 — 참조하는 eKYC 제출 건이approved상태인지 확인하세요.
2-2. 토큰 검증 실패
FaceAuth 프로젝트에서 토큰 만료 조건 설정을 활성화한 경우,token 검증 실패 시 TK- 계열 에러 페이지로 이동합니다. 코드(TK-10000 ~ TK-10004)와 문구는 에러 코드와 에러 페이지의 토큰 에러 페이지 항목에서 확인하세요.
FaceAuth의
token은 메인 프로젝트(ID Check)의 프라이빗 모드 토큰·사전등록 토큰과 별개로 동작하며, 토큰 DB와 만료 파이프라인이 분리되어 있습니다. 동작 방식은 FaceAuth 시작하기 — 요청 파라미터들에 대한 정의, 대시보드 설정은 FACE AUTH 가이드 — 토큰 만료 조건 설정을 참고하세요.3. 사전 로드 단계 서버 오류
프로젝트 옵션과 참조 제출 건을 조회하는 과정에서 발생하는 서버 오류입니다. 모두SE- 계열이며, 사용자에게는 재시도 안내가 표시됩니다.
4. 인증 처리 단계 사용자 노출 문구
셀피 촬영 후 인증 API 호출 결과에 따라 두 가지로 분기합니다.4-1. HTTP StatusCode가 200이 아닌 경우 (비정상 처리)
원인을 구분하지 않고 단일 문구로 통일하여 AlertPopup 형식으로 표시합니다.원문 문자열은 개행 문자를 포함합니다:
"요청사항을 처리하는데 실패했습니다.\n다시 시도해주세요."내부 에러 코드는 사용자에게 노출되지 않습니다. 원인 파악은 웹훅 또는 GET/FaceAuth 응답으로 하세요.4-2. HTTP StatusCode가 200이지만 정상 처리되지 못한 경우 (거절)
auth_status가 rejected로 반환되며, fail_code에 따라 아래 문구가 표시됩니다.
no_face와 face_compare_fail이 같은 문구를 공유하며, active_liveness_fail과 passive_liveness_fail도 동일합니다. 어떤 검증이 실패했는지는 문구가 아니라 fail_code로 판별하세요.위 표는 사용자 화면에 노출되는 문구입니다. API 응답과 웹훅으로 전달되는
rejected_comment 원문(예: face compare similarity score is lower than threshold)은 별도 값이며, POST/Faceauth — 실패 코드에서 확인하세요.4-3. 라이브니스 실패 코드
라이브니스 검증은 프로젝트 정책의livenessMode(passive / active) 설정에 따라 실행되며, 실패 시 아래 코드가 반환됩니다.
rejected_comment는 API 응답과 웹훅으로 전달되는 값입니다. 두 코드의 코멘트 문구는 동일하므로, 어느 라이브니스가 실패했는지는 fail_code로 구분하세요.5. 재시도 정책
6. 관련 문서
FaceAuth 시작하기
Face Auth URL 구조와 QueryString 파라미터 정의
POST/Faceauth
API 방식의 실패 코드 및 에러 코드
에러 코드와 에러 페이지
전체 에러 코드 체계 및 에러 페이지 정의
FACE AUTH 가이드
대시보드 정책·임계값·토큰 만료 설정