개요
이 문서는 라이브폼 모바일 여정에서 노출되는 에러 페이지를 유형별로 분류해 에러 코드, URL 경로, 사용자 메시지를 제공합니다. 최종 사용자가 만나는 에러 메시지에 대해 실제 라우팅 경로와 발생 조건을 정확하게 확인하고 업무나 고객 지원에 활용할 수 있습니다.모든 에러 페이지는 다음의 4 유형으로 구분됩니다.
/error-page/:errorType/error-page/token-*/face-retry/:faceErrorCodeError Boundary
에러 코드 카테고리 체계
에러 코드 형식:카테고리-숫자5자리 (예: NF-10000)
| 카테고리 | 접두사 | 풀네임 | 번호 대역 | 의미 |
|---|---|---|---|---|
| General | 개발자 코드 | Legacy | — | 각 오류 유형별로 개발자 코드에 정의 |
| Not Found | NF | Not Found | 10000번대 | 존재하지 않는 경로로 직접 접근 |
| Quality Score | QS | Quality Score | 10000~30000 | IP 조회 시 발생한 에러 케이스 |
| Queueing Error | QE | Queueing Error | 20000번대 | 엔진 대기열 과부하 관련 에러 |
| Parameter Validation | PV | Parameter Validation | 40000번대 | 쿼리스트링 파라미터 누락 / 잘못된 값 / 옵션 충돌 |
| Server Error | SE | Server Error | 50000번대 | API 호출 실패 또는 서버 에러 |
| Runtime | RT | Runtime Error | 60000번대 | 프론트엔드 런타임 에러 (React ErrorBoundary, try/catch 예외) |
일반 에러 페이지 (/error-page/:errorType)
🔒 인증·권한 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 페이지 없음 | page-not-found | /error-page/page-not-found | ”페이지를 찾을 수 없습니다” | 존재하지 않는 URL을 직접 입력하거나 만료된 즐겨찾기 링크를 열었을 때 나타납니다. |
| 서비스 차단 | service-blocked | /error-page/service-blocked | ”제출이 일시 중단 되었습니다” | 운영자가 제출을 잠시 막아둔 시간대에 사용자가 계속 접속할 때 안내됩니다. |
| 유효하지 않은 경로 | bad-path | /error-page/bad-path | ”잘못된 URL 경로” | 공유받은 링크를 임의로 수정하거나 허용되지 않은 경로로 이동했을 때 발생합니다. |
| 새로고침 감지 | refresh | /error-page/refresh | ”새로고침 감지” | 진행 중 새로고침·뒤로가기를 눌러 세션이 끊기면 처음부터 다시 시작하도록 표시됩니다. |
| 미지원 브라우저 | invalid-browser | /error-page/invalid-browser | ”지원하지 않는 브라우저” | 구형 브라우저나 WebAssembly를 지원하지 않는 환경에서 접속하면 최신 브라우저로 변경해야 합니다. |
| 해시 검증 실패 | hash_problem | /error-page/hash_problem | ”해시 검증 문제” | 여러 탭을 열거나 단계를 건너뛰어 데이터가 꼬였을 때 처음 단계로 돌아가야 합니다. |
| 암호화 전용 모드 | encrypted_only | /error-page/encrypted_only | ”암호화되지 않은 접근” | option_encryptedOnly=true인 프로젝트에서 암호화되지 않은 쿼리스트링으로 접근하거나 pid, lang, encrypted 외 허용되지 않은 파라미터가 포함된 경우 발생합니다. |
📅 프로젝트 상태 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 프로젝트 종료 | project-closed | /error-page/project-closed | ”현재 프로젝트는 종료되어 접근이 제한되었습니다” | 이미 종료된 캠페인 링크를 다시 열면 더 이상 진행할 수 없다는 메시지가 표시됩니다. |
| 기간 만료 | period | /error-page/period | ”프로젝트 기간 만료” | 제출 가능 기간이 끝난 뒤 늦게 접속하면 기간이 지났다는 안내가 나옵니다. |
| 제출 횟수 제한 | submission-number-limit | /error-page/submission-number-limit | ”제출건이 15개를 초과하였습니다” | 체험용(trial) 프로젝트에서 허용 횟수(15회)를 넘겨 계속 제출하면 제한 안내와 함께 중단됩니다. |
📤 제출 상태 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 이미 승인됨 | already_approved | /error-page/already_approved | ”이미 검증 완료된 모바일입니다” | 같은 기기·브라우저에서 이미 승인받았는데 다시 시도하면 남은 대기 시간과 함께 차단됩니다. |
| 이미 거부됨 | already_rejected | /error-page/already_rejected | ”이미 거부된 제출” | 거부된 뒤 대기 시간이 끝나기 전에 재시도하면 기다리라는 메시지가 나타납니다. |
| 승인 대기 중 | already_pending | /error-page/already_pending | ”현재 검토 중입니다” | 이전 제출이 아직 심사 중인데 추가 제출을 시도할 때 더 이상 진행하지 못합니다. |
| 처리 완료(승인) | processed_submission-approved | /error-page/processed_submission-approved | ”이미 처리된 제출 (승인됨)“ | 승인된 결과 화면을 다시 열어도 추가 조치가 필요 없다고 안내합니다. |
| 처리 완료(거부) | processed_submission-rejected | /error-page/processed_submission-rejected | ”검증이 거부되었습니다” | 거부된 제출을 동일하게 다시 열면 잔여 대기 시간과 함께 재시도 시점을 알려 줍니다. |
| IP 승인 이력 | ip_already_approved | /error-page/ip_already_approved | ”해당 IP로 이미 승인됨” | 같은 네트워크(IP)에서 이미 완료된 검증이 있을 때 다른 사람이 다시 시도하면 제한됩니다. |
| IP 거부 이력 | ip_already_rejected | /error-page/ip_already_rejected | ”해당 IP로 이미 거부됨” | 동일 IP로 여러 번 실패하거나 거부된 상태에서 다시 접속하면 다른 네트워크를 사용하라는 안내가 나옵니다. |
📧 이메일 관련 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 이메일 거부 이력 | email_already_rejected | /error-page/email_already_rejected | ”검증이 거부되었습니다 / 해당 이메일로 이미 거부됨” | 이미 거부된 이메일 주소로 다시 제출하면 대기 시간과 함께 재시도 불가 안내가 표시됩니다. |
🛡️ 보안·사기 탐지 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 위조 의심 | suspected-forgery | /error-page/suspected-forgery | ”위조 의심 감지” | 촬영한 신분증이 흐릿하거나 조작 흔적이 있어 진품으로 확인되지 않을 때 다시 촬영해야 합니다. |
| 파일 업로드 불가 | not-allow-file-upload | /error-page/not-allow-file-upload | ”파일 업로드가 허용되지 않습니다” | 시크릿 모드나 보안 브라우저처럼 카메라·파일 권한이 막힌 환경에서 업로드를 시도하면 권한을 허용하거나 다른 기기를 사용해야 합니다. |
| 얼굴 중복 감지 | face_validation_error | /error-page/face_validation_error | ”중복된 얼굴이 탐지되었습니다” | 이전 제출과 동일한 얼굴이 감지되어 한 사람이 여러 번 시도하는 것으로 판단될 때 고객 지원 안내가 뜹니다. |
| 비정상 행동 | abnormal_action | /error-page/abnormal_action | ”비정상적인 행동이 감지되었습니다” | 캡처 화면 업로드, 과도한 색상 보정, 동일 셀카 복사 등 비정상 촬영 방식이 감지되면 정상적인 절차로 다시 진행해야 합니다. |
🌍 IP 리스크 오류
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 카테고리 실패 | ipRisk_failCategory | /error-page/ipRisk_failCategory | ”IP 리스크 카테고리 실패” | VPN, Tor, 데이터센터 등 고위험 네트워크에서 접속하면 다른 네트워크로 전환해야 합니다. |
| 거리 검증 실패 | distanceChecks_ipGeo | /error-page/distanceChecks_ipGeo | ”IP 위치 거리 체크 실패” | GPS 위치와 IP 위치가 멀리 떨어져 있을 때(예: 국내 GPS + 해외 VPN) VPN을 끄고 실제 위치에서 접속해야 합니다. |
| 블랙리스트 국가 | blackliskCountries | /error-page/blackliskCountries | ”블랙리스트 국가” | 차단된 국가에서 접속하면 해당 국가에서는 서비스를 이용할 수 없다는 안내가 표시됩니다. |
| 시간 제한 | ipRisk_durationHours | /error-page/ipRisk_durationHours | ”IP 리스크 기간 제한” | 위험한 네트워크에서 반복 시도해 IP가 일정 시간 잠기면 남은 시간이 끝난 뒤에만 재시도할 수 있습니다. |
⏱️ Rate Limit · Lockout
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 요청 횟수 초과 | rate_limit_exceeded | /error-page/rate_limit_exceeded | ”요청 횟수 제한 초과” | 짧은 시간에 반복으로 새로고침하거나 제출해 요청 한도를 넘기면 잠시 대기해야 합니다. |
| 계정 잠금 | locked_out | /error-page/locked_out | ”계정 잠김” | 여러 차례 실패나 의심되는 활동으로 계정이 잠기면 표시된 시간이 지나야 자동 해제됩니다. |
| 트래픽 과부하 | traffic_overload | /error-page/traffic_overload | ”트래픽 과부하” | 제출 상태 폴링 시도가 32회를 초과하면 서버 부하 상태로 판단되어 잠시 후 다시 시도하도록 안내됩니다. |
📍 NF — Not Found
경로를 찾을 수 없을 때 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
NF-10000 | /error-page/not-found | ”페이지를 찾을 수 없습니다” 요청하신 페이지가 존재하지 않습니다. URL을 다시 확인해 주세요. | ”Page not found” The page you requested does not exist. Please check the URL and try again. | 라우터에 정의되지 않은 경로로 직접 접근했을 때 발생합니다. Mobile/PC 모두 와일드카드(*)에 걸려 이 페이지로 이동합니다. |
NF-10001 | /error-page/invalid-path | ”잘못된 접근 경로입니다” 허용되지 않은 경로로 접근하셨습니다. 올바른 URL로 다시 시도해 주세요. | ”Invalid access path” You accessed an unauthorized path. Please try again with the correct URL. | URL 경로 자체는 존재하지만 허용된 초기 진입 경로 목록(VALID_INITIAL_PATH)에 없는 경로로 접근한 경우 발생합니다. |
⚠️ QS — Quality Score
IP 조회 시 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
QS-10000 | /error-page/abnormal_verification_denied | ”비정상 검증 거부” 짧은 시간에 위험 행동을 반복해 신뢰 점수가 낮아졌습니다. 안내된 시간이 지날 때까지 기다려야 합니다. | ”Abnormal verification denied” Rapid risky attempts lowered the trust score. You must wait for the displayed timer to expire. | IP 체커에서 48시간 대기 판정이 내려졌을 때 발생합니다. |
QS-20000 | /error-page/abnormal_rejected | ”비정상 거부” 심각한 이상 징후가 확인되어 즉시 거부되었습니다. 보안 이슈를 해소한 후에만 재시도할 수 있습니다. | ”Abnormal rejection” Severe anomalies triggered an immediate rejection. Security issues must be resolved before retrying. | IP 체커에서 fraud score 90점 이상으로 판정되었을 때 발생합니다. |
QS-30000 | /error-page/ipqs_system_error | ”IPQS 시스템 에러” IP 조회가 시스템 오류로 인하여 실패했습니다. 잠시 후 다시 시도해 주세요. | ”IPQS system error” The IP lookup failed due to a system error. Please try again later. | IP 체커에서 클라이언트/서버 오류가 발생했을 때 나타납니다. |
📦 QE — Queueing Error
엔진 대기열 과부하 시 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
QE-20000 | /error-page/queueing-timeout | ”대기열 과부하” 일시적인 트래픽 급증과 대기열 과부하로 제출을 처리하지 못했습니다. 잠시 후 다시 시도해 주세요. | ”Queue overload” We couldn’t process your submission due to unusually high traffic and an overloaded queue. Please try again in a moment. | 엔진 사용 대기열 과부하로 인하여 현재 유저의 데이터를 서버에서 처리할 수 없는 경우 발생합니다. |
🔧 PV — Parameter Validation
쿼리스트링 파라미터 누락, 잘못된 값, 옵션 충돌 시 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
PV-40000 | /error-page/missing-pid | ”필수 파라미터가 누락되었습니다” 프로젝트 ID(pid)가 URL에 포함되지 않았습니다. 올바른 링크를 통해 다시 접근해 주세요. | ”Required parameter is missing” The project ID (pid) is not included in the URL. Please access again via the correct link. | URL 쿼리스트링에 pid 파라미터가 없는 경우 발생합니다. pid는 프로젝트 식별자로 모든 요청에 필수입니다. |
PV-40001 | /error-page/invalid-action | ”유효하지 않은 요청입니다” action 파라미터 값이 올바르지 않거나 필수 파라미터가 누락되었습니다. | ”Invalid request” The action parameter value is invalid or required parameters are missing. | action 파라미터가 허용된 값(addveri)이 아니거나, action=addveri임에도 pid 또는 sid가 함께 없는 경우 발생합니다. |
PV-40002 | /error-page/invalid-distance-option | ”옵션 설정이 올바르지 않습니다” 거리 검사 옵션 값이 유효하지 않습니다. 설정을 확인하고 다시 시도해 주세요. | ”Option configuration is invalid” The distance check option value is invalid. Please check the settings and try again. | distanceCheckSource 옵션은 전달됐으나 함께 필요한 distanceMaxDistanceKm 값이 숫자 형식이 아닌 경우 발생합니다. |
PV-40003 | /error-page/invalid-iprisk-option | ”옵션 설정이 올바르지 않습니다” IP 리스크 옵션 값이 유효하지 않습니다. 설정을 확인하고 다시 시도해 주세요. | ”Option configuration is invalid” The IP risk option value is invalid. Please check the settings and try again. | ipRiskCategory 옵션은 전달됐으나 함께 필요한 ipRiskDurationHours 값이 숫자 형식이 아닌 경우 발생합니다. |
PV-40004 | /error-page/conflicting-projection | ”파라미터 설정이 충돌합니다” projectionName과 projectionId는 동시에 사용할 수 없습니다. 둘 중 하나만 설정해 주세요. | ”Parameter configuration conflict” projectionName and projectionId cannot be used at the same time. Please configure only one of them. | projectionName과 projectionId를 동시에 사용한 경우 발생합니다. 둘 중 하나만 허용됩니다. |
PV-40010 | /error-page/blacklisted-country | ”서비스를 이용할 수 없는 국가입니다” 선택하신 국가에서는 본인 인증 서비스를 제공하지 않습니다. | ”Service is unavailable in this country” Identity verification service is not available in the selected country. | selectedIssuingCountry로 지정된 국가가 블랙리스트 국가인 경우 발생합니다. |
PV-40011 | /error-page/blacklisted-allowed-country | ”허용 국가 설정이 올바르지 않습니다” 허용 국가 목록에 서비스가 제한된 국가가 포함되어 있습니다. 설정을 확인하고 다시 시도해 주세요. | ”Allowed country configuration is invalid” The allowed country list includes a country with restricted service. Please check the settings and try again. | allowedCountries 목록 안에 블랙리스트 국가가 하나 이상 포함된 경우 발생합니다. |
PV-40012 | /error-page/conflicting-universal-idtype | ”신분증 옵션 설정이 충돌합니다” 전체 허용 모드(universal)와 특정 신분증 지정(selectedIdType)은 함께 사용할 수 없습니다. 설정을 확인하고 다시 시도해 주세요. | ”ID type option configuration conflict” Universal mode and specific ID type selection (selectedIdType) cannot be used together. Please check the settings and try again. | option_universal=true로 전체 신분증 허용 모드인데 selectedIdType으로 특정 신분증을 동시에 지정한 경우 발생합니다. |
PV-40013 | /error-page/missing-issuing-country | ”발급 국가 정보가 누락되었습니다” 신분증 종류를 지정하려면 발급 국가도 함께 설정해야 합니다. 설정을 확인하고 다시 시도해 주세요. | ”Issuing country information is missing” To specify an ID type, the issuing country must also be configured. Please check the settings and try again. | selectedIdType(신분증 종류)은 있으나 필수 선행 조건인 selectedIssuingCountry(발급 국가)가 없는 경우 발생합니다. |
PV-40014 | /error-page/conflicting-knowledge-idtype | ”인증 방식 설정이 충돌합니다” 지식 기반 인증(knowledge) 모드에서는 신분증 종류를 별도로 지정할 수 없습니다. 설정을 확인하고 다시 시도해 주세요. | ”Authentication method configuration conflict” In knowledge-based authentication mode, the ID type cannot be specified separately. Please check the settings and try again. | authType=knowledge(지식 기반 인증) 모드인데 selectedIdType(신분증 종류)도 함께 지정한 경우 발생합니다. |
PV-40015 | /error-page/missing-faceauth-pid | ”인증 정보가 누락되었습니다” 얼굴 인증에 필요한 필수 파라미터(pid 또는 sid)가 없습니다. 올바른 링크를 통해 다시 접근해 주세요. | ”Authentication information is missing” Required parameters (pid or sid) for face authentication are missing. Please access again via the correct link. | faceAuth(얼굴 인증) 진입 시 pid 또는 sid 중 하나라도 없는 경우 발생합니다. |
PV-40016 | /error-page/conflicting-knowledge-skip | ”검증 옵션 설정이 충돌합니다” 지식 검증 건너뜀(skip)과 얼굴 비교 비활성화는 함께 사용할 수 없습니다. 설정을 확인하고 다시 시도해 주세요. | ”Validation option configuration conflict” Skipping knowledge validation and disabling face comparison cannot be used together. Please check the settings and try again. | knowledgeField=skip(지식 검증 건너뜀)으로 설정했는데 option_validationFaceCompare=false도 함께 설정한 경우 발생합니다. |
PV-40017 | /error-page/conflicting-knowledge-field | ”지식 검증 필드 설정이 충돌합니다” knowledgeField의 skip 옵션은 다른 필드와 함께 사용할 수 없습니다. skip은 단독으로만 설정해 주세요. | ”Knowledge validation field configuration conflict” The skip option in knowledgeField cannot be used with other fields. Please set skip as a standalone option. | knowledgeField에 skip과 다른 필드 옵션을 동시에 선언한 경우 발생합니다. skip은 단독으로만 사용 가능합니다. |
🖥️ SE — Server Error
API 호출 실패 또는 서버 에러 시 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
SE-50000 | /error-page/project-load-error | ”프로젝트 정보를 불러올 수 없습니다” 서버에서 프로젝트 설정을 가져오는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Unable to load project information” An error occurred while fetching project settings from the server. Please try again later. | 앱 초기 진입 시 프로젝트 설정을 가져오는 projectOptions API 호출 자체가 실패한 경우 발생합니다. |
SE-50001 | /error-page/token-check-error | ”토큰 확인 중 오류가 발생했습니다” 서버와의 통신 중 문제가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”An error occurred while verifying the token” A problem occurred while communicating with the server. Please try again later. | 토큰 유효성을 검증하는 checkingToken API 호출 중 예외가 발생한 경우입니다. |
SE-50002 | /error-page/validation-api-error | ”검증 서비스 오류가 발생했습니다” 주소 검증 중 서버 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Validation service error” A server error occurred during address validation. Please try again later. | 주소 검증 API(/live/internal/validation) 호출 결과 에러 응답이 온 경우 발생합니다. |
SE-50010 | /error-page/faceauth-preload-error | ”얼굴 인증 초기화에 실패했습니다” 얼굴 인증 준비 중 서버 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Face authentication initialization failed” A server error occurred while preparing face authentication. Please try again later. | faceAuth 진입 전 사전 데이터를 로드하는 첫 번째 API 쿼리가 실패한 경우 발생합니다. |
SE-50011 | /error-page/faceauth-preload-error-2 | ”얼굴 인증 초기화에 실패했습니다” 얼굴 인증 추가 데이터 로드 중 서버 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Face authentication initialization failed” A server error occurred while loading additional face authentication data. Please try again later. | faceAuth 진입 전 사전 데이터를 로드하는 두 번째 API 쿼리가 실패한 경우 발생합니다. |
SE-50012 | /error-page/faceauth-submission-error | ”얼굴 인증 상태 확인에 실패했습니다” 인증 제출 상태를 확인하는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Failed to verify face authentication status” An error occurred while checking the authentication submission status. Please try again later. | faceAuth에서 checkSubmission API는 응답했으나 result 값이 유효하지 않은(falsy) 경우 발생합니다. |
SE-50013 | /error-page/faceauth-token-error | ”얼굴 인증 토큰 처리에 실패했습니다” 인증 토큰을 등록하는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Face authentication token processing failed” An error occurred while registering the authentication token. Please try again later. | faceAuth에서 insertToken API 호출 중 예외가 발생한 경우입니다. |
SE-50014 | /error-page/faceauth-project-error | ”얼굴 인증 프로젝트 정보를 불러올 수 없습니다” 서버에서 프로젝트 데이터를 가져오는 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. | ”Unable to load face authentication project information” An error occurred while fetching project data from the server. Please try again later. | faceAuth 프로젝트 데이터를 조회하는 API 호출이 실패한 경우 발생합니다. |
SE-50015 | /error-page/validation-code-error | ”검증에 실패했습니다” 주소 검증 결과 오류 코드가 반환되었습니다. 입력 정보를 확인하고 다시 시도해 주세요. | ”Validation failed” An error code was returned from address validation. Please check your information and try again. | 주소 검증 API 응답에 errorCode 필드가 포함된 경우 발생합니다. API는 응답했으나 검증 자체가 실패한 상태입니다. |
⚡ RT — Runtime Error
프론트엔드 런타임 에러 시 발생하는 에러 코드입니다.| 에러 코드 | URL | 사용자 메시지 (KO) | 사용자 메시지 (EN) | 발생 상황 |
|---|---|---|---|---|
RT-60000 | /error-page/runtime-error | ”오류가 발생했습니다” 예기치 않은 오류가 발생했습니다. 페이지를 새로고침하거나 처음부터 다시 시도해 주세요. | ”An error occurred” An unexpected error occurred. Please refresh the page or start over. | /qr, /knowledge-qr, /face-auth-qr 라우트에서 React ErrorBoundary가 발동한 경우 발생합니다. |
RT-60001 | /error-page/token-runtime-error | ”토큰 처리 중 오류가 발생했습니다” 예기치 않은 오류가 발생했습니다. 페이지를 새로고침하거나 처음부터 다시 시도해 주세요. | ”An error occurred during token processing” An unexpected error occurred. Please refresh the page or start over. | useTokenCheck 훅 내부 try/catch에서 예외가 포착된 경우 발생합니다. 토큰 처리 중 예상치 못한 런타임 오류입니다. |
🔵 토큰 에러 페이지 (/error-page/token-*)
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 토큰 누락 | token-missing | /error-page/token-missing | ”토큰 ID가 작동되지 않았습니다” / 부제: “다른 모바일 기기에서 시도해주세요” | 공유 링크를 복사하면서 토큰 파라미터가 빠졌거나 불완전한 URL을 열 때 나타납니다. |
| 토큰 만료 | token-expired | /error-page/token-expired | ”토큰 만료” / 부제 동일 | 오래전에 받은 링크나 재사용한 토큰으로 접속하면 만료 안내가 표시됩니다. |
| 토큰 승인 완료 | token-approved | /error-page/token-approved | ”토큰 이미 승인됨” | 이미 다른 기기에서 해당 토큰으로 인증을 마친 뒤 다시 열면 중복 진행이 차단됩니다. |
| 토큰 검토 중 | token-pending | /error-page/token-pending | ”토큰 검토 중” | 같은 토큰으로 보낸 제출이 아직 검토 중인데 재진입하면 심사 완료까지 기다려야 합니다. |
| 토큰 거부 | token-rejected | /error-page/token-rejected | ”토큰 거부됨” | 이 토큰으로 제출한 건이 거부된 상태에서 다시 시도하면 담당자에게 문의하라는 메시지가 노출됩니다. |
🔄 얼굴 인증 재시도 (/face-retry/:faceErrorCode)
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 동적 얼굴 재촬영 | face-retry/:faceErrorCode | /face-retry/:faceErrorCode | 각 에러 코드별 번역 키(기본: “다시 촬영”) / 버튼: “다시 촬영” | 조명이 어둡거나 얼굴이 가이드라인 밖으로 벗어나는 등 촬영 품질이 부족하면 재촬영을 안내하며, 특정 코드(invalid_submission_status)일 땐 버튼이 숨겨집니다. |
❌ 런타임 에러 (Error Boundary)
| 유형 | 개발자 코드 | URL | 사용자 메시지 | 발생 상황 |
|---|---|---|---|---|
| 런타임 에러 | Next.js Error Boundary | — | 기본: “요청이 실패하였습니다”, “KYC 검증이 거부되었습니다” 특수: “지원하지 않는 브라우저”(WebAssembly 에러), “This browser does not support Storage functionality”(Storage 미지원) | 네트워크 단절, 강제 새로고침, 시크릿 모드처럼 저장 기능이 막힌 환경에서 앱이 비정상 종료될 때 표시되며, “다시 시도” 버튼으로 재시도하거나 최신 브라우저·정상 모드로 전환해야 합니다. |
각 테이블을 기반으로 고객 지원, 모니터링 알림, QA 테스트 케이스를 매핑하면 동일한 화면을 바라보는 모든 이해관계자가 빠르게 상황을 파악할 수 있습니다.