오류 코드 안내
에러 코드 및 대응 가이드
eKYC 연동 중 발생할 수 있는 클라이언트/서버 에러 코드 목록과 그에 대한 원인 및 대응 방법을 정리했어요.
에러가 발생했을 때 이 가이드를 참고하면, 빠르게 원인을 파악하고 사용자 안내나 재처리 방식을 결정할 수 있어요.
1. 에러 코드 확인 방법
eKYC 연동 과정에서 아래 화면처럼 ****에러 코드와 함께 인증 실패 안내 메시지가 표시돼요.
이 코드를 기반으로 어떤 문제가 발생했는지 확인해 주세요.
※ 에러 코드가 표시되지 않거나 result 값이 없는 경우에는 네트워크 연결 문제일 수 있어요.
2. Client 에러 코드
| 코드 | 설명 | 제안 액션 |
|---|---|---|
| CE002 | 신분증 사진에서 얼굴 감지 실패 | 다른 각도의 사진 촬영 유도 |
| CE003 | 동일 (CE002) | 동일 |
| CE004 | 실제 얼굴 여부 인증 실패 (사진/영상 시도) | 실시간 얼굴 촬영 재유도 + 안내 문구 노출 |
| CE005 | 얼굴이 명확히 감지되지 않음 | 주변 조명 안내 및 재시도 유도 |
| CE006 | 얼굴 유사도 부족 | 수동심사로 전환 또는 고객센터 안내 |
CE010 자주 발생 | token 파싱 오류 (JSON 포맷 에러 등) | 요청 파라미터 구조 확인 및 디코딩 로직 점검 |
| CE011 | 연동 계정 인증 실패 (sign-in 실패) | 연동 계정 재확인 및 사전 로그인 확인 필요 |
| CE012 | 연동정보 인증 실패 (AccessToken 오류) | AccessToken 유효성 확인 및 재발급 요청 |
CE013 자주 발생 | 필수 정보 누락 | 필수 입력 필드 점검 (이름, 생년월일 등) |
| CE014 | 필수 정보 형식 오류 | 입력 형식 유효성 검증 추가 필요 |
| CE015 | 추가 인증 기능 활성화 되었으나 항목 없음 | 인증 모듈 설정 재검토 또는 UI 표시 검증 |
| CE017 | 웹소켓 연결 실패 | 네트워크 상태 확인, WebSocket 재시도 처리 |
| CE019 | 인증 모듈이 모두 비활성화됨 | 최소 1개 모듈 활성화 필요 (예: OCR) |
| CF016 | 평생계좌번호로 실명인증 실패 | 일반 계좌번호 사용 권고 또는 사용자 선택 유도 |
| CF018 | 신분증 종류 선택과 OCR 결과 불일치 | 사용자가 선택한 신분증 유형 확인 로직 추가 |
| CF019 | 신분증 발급일자 인식 실패 | 인식 오류 알림 후 재촬영 유도 |
| CE580 | 클라이언트 내부 오류 | 오류 로그 수집 후 고객센터 안내 |
| SF001 | 신분증에서 얼굴 감지 실패 (server fallback) | 고해상도 이미지 재업로드 유도 |
| CE999 | 클라이언트 미정의 오류 | 전체 흐름 재시도 안내 또는 고객센터 연결 |
※ 에러 코드가 표시되지 않거나 result 값이 없는 경우, 네트워크 에러일 가능성이 있습니다.
3. Server 에러 코드
| 코드 | 설명 | 제안 액션 |
|---|---|---|
| N100 | 정상 처리 됨 | 별도 조치 불필요 (성공 처리 진행) |
| F540 | 요청한 데이터를 찾을 수 없음 | id 값 또는 인증 건의 존재 여부 확인 |
| E535 | 요청 데이터 형식 오류 또는 유효하지 않은 값 포함 | 요청 바디나 파라미터의 타입, 필드명, 값 검증 필요 |
| E300 | 토큰 인증 과정 중 오류 발생 | 인증 토큰 유효성 검토, 재발급 시도 |
| E301 | 토큰 만료됨 | 토큰 재발급 후 재요청 수행 |
| E302 | 토큰이 유효하지 않음 | 올바른 계정 정보로 토큰 발급 여부 확인 |
| E531 | 요청 데이터가 비어 있음 | 필수 필드 누락 여부 확인, 요청 바디 유효성 검증 |
| F301 | 계정 정보가 잘못됨 | reviewer 계정 ID, username, password 확인 |
| F302 | 최종 승인이 되지 않은 계정 | 관리자 또는 useB 측에 계정 활성화 상태 확인 요청 |
| F303 | 비활성화된 계정 사용 | 계정 활성화 요청 필요 또는 다른 계정 사용 |
| F304 | 비활성화된 계좌 사용 | 계좌가 유효한지 확인 후 다른 계좌로 시도 |
| F305 | 계정이 잠김 | 일정 횟수 이상 실패 시 계정 잠금 → 관리자 조치 필요 |
| E530 | 필수 정보 확인 오류 | 이름, 생년월일, 계좌번호 등 필수 필드 입력 여부 재확인 |
| E532 | 요청한 데이터를 불러오는 데 실패 | 네트워크 또는 서버 쿼리 오류 → 재시도 또는 로그 확인 |
| E533 | 필수 정보를 저장하는 중 오류 발생 | 저장 대상 데이터 유효성 확인, 재시도 권장 |
| E534 | 요청 쿼리 파라미터에 문제 있음 | 쿼리스트링 확인 (예: id, type 등) |
| E580 | 내부 데이터베이스(DB)와의 통신 중 오류 | 일시적 장애 가능 → 일정 시간 후 재시도, 로그 수집 |
| E704 | 이미지 다운로드 중 오류 발생 | 이미지 URL, 권한, 만료 여부 확인 후 재시도 |