페이지 이동경로
- 문서>
- 카카오톡 인증 서비스>
- 문제 해결
카카오톡 인증 서비스
문제 해결
이 문서는 카카오톡 인증 서비스 이용 중 발생할 수 있는 문제의 해결 방법을 안내합니다.
에러 코드
카카오톡 인증
| 코드 | 설명 | HTTP 상태 코드 |
|---|---|---|
E0001 |
서버 내부에서 처리 중 에러가 발생한 경우 해결 방법: 재시도 |
400 |
E0002 |
서버 점검 중인 경우 해결 방법: 기능 제공 일시 중단 또는 사용자 안내 처리 |
503 |
E1001 |
필수 파라미터를 포함하지 않은 경우, 또는 파라미터의 데이터 타입이 적절하지 않거나 허용된 범위를 벗어난 경우 해결 방법: 요청 파라미터 확인 카카오톡에 연결된 번호가 해외 번호인 경우 해결 방법: 카카오톡에 연결된 번호 확인 |
400 |
E1002 |
해당 API에 대한 요청 권한이 없거나 요청 정보가 잘못된 경우 해결 방법: REST API 레퍼런스 에러 코드의 코드별 해결 방법 수행 |
403 |
E1004 |
HTTP 헤더(Header)가 없거나 잘못된 경우 해결 방법: 이용기관 앱 REST API 키 및 딜러사 앱 REST API 키를 헤더에 포함해 재요청 |
401 |
E1005 |
settle_id 파라미터가 없거나 잘못된 경우해결 방법: settle_id를 포함해 재요청 |
400 |
E1006 |
desc 데이터가 계약 내용과 다르거나 포맷이 맞지 않는 경우해결 방법: 개발 가이드를 참고해 전자서명 요청하기의 desc 포맷 확인 후 유효한 값으로 재요청 |
400 |
E1007 |
상품 종류에 해당하지 않는 도메인으로 호출한 경우 해결 방법: 상품 종류에 해당하는 도메인으로 요청(예: 테스트 상품 K1110T의 경우 cbt-cert-sign.kakao.com으로, 운영 상품 K1110의 경우 cert-sign.kakao.com 도메인으로 요청) |
400 |
E2001 |
존재하지 않는 카카오계정으로 요청한 경우 해결 방법: 이름, 전화번호, 생년월일 또는 CI에 해당하는 카카오계정을 확인할 수 없는 경우, 사용자 정보 확인 |
400 |
E2002 |
K1100: 카카오계정의 전화번호, 이름, 생년월일이 요청 파라미터와 일치하지 않는 경우K1300: 카카오 계정의 ci가 요청 파라미터와 일치하지 않는 경우해결 방법: 요청 시 파라미터로 전달된 사용자 정보와 카카오톡의 카카오계정 정보가 일치하지 않으면 전자서명이 불가함을 사용자에게 안내 |
400 |
E2003 |
tx_id에 대한 정보가 존재하지 않는 경우해결 방법: 전자서명 준비하기 API를 재호출해 tx_id를 새롭게 발급받아 올바른 tx_id로 재요청 |
400 |
E2004 |
전자서명 요청하기 API를 연속해서 2회 이상 호출한 경우 해결 방법: 전자서명 요청하기 API는 연속해서 호출할 수 없음, 사용자에게 전자서명이 올바르게 전달되었는지 확인하려면 전자서명 상태 확인하기 API 사용 |
400 |
E2005 |
카카오계정의 상태가 휴면, 제재, 탈퇴, 보호 상태인 경우 해결 방법: 사용자의 카카오계정이 카카오톡 인증 서비스를 이용할 수 없는 상태임을 안내 |
400 |
E2006 |
사용자 서명이 완료되기 전 전자서명 검증하기 API를 호출한 경우 해결 방법: 전자서명 상태 확인하기 API를 통해 서명의 진행 상태가 COMPLETE로 변경된 것을 확인한 후 전자서명 검증하기 API 호출 |
400 |
E2007 |
서명 요청이 만료된 후 전자서명 검증 API를 호출한 경우 해결 방법: 전자서명 준비하기 API 재호출 |
400 |
E2008 |
전자서명 검증하기 API를 2회 이상 호출한 경우 해결 방법 : 사용자에게 서명 실패로 안내하고 전자서명 준비하기부터 다시 진행 |
400 |
E2009 |
사용자 환경으로 인해 알림톡 발송에 실패한 경우 해결 방법: 사용자의 알림톡 차단 여부 확인이 필요함을 안내(사용자 환경은 개인정보로 제공 불가) |
400 |
E2010 |
카카오계정에 본인인증 정보가 없는 경우 해결 방법: 카카오톡에서 인증서를 발급받도록 안내 카카오톡의 [더보기] > [지갑] > [인증서 발급받기] 또는 카카오톡 지갑 채널로 발송된 인증서 발급 안내 메시지를 통해 인증서 발급 가능 |
400 |
E2011 |
동일 CI로 가입된 카카오계정이 2개 이상이며, 유효한 인증서가 없는 경우 해결 방법: 카카오톡에서 인증서를 발급받도록 안내(카카오톡의 [더보기] > [지갑] > [인증서 발급받기]) |
400 |
E2012 |
카카오톡 전자서명(K3500) 사용 시 documents의 순서가 document_tx_id와 잘못 매핑(Mapping)된 경우해결 방법: 전자서명 준비하기 API 재호출 참고: documents 목록 주의사항 |
400 |
E2013 |
사용자가 서명을 완료하고 일정시간(10분)이 지난 후에 전자서명 검증하기 API를 요청하는 경우 해결 방법 : 전자서명 준비하기 API 재호출 |
400 |
E2017 |
사용자가 서명을 완료하고 일정시간(10분)이 지난 후에 서명자 정보 가져오기 API를 호출하는 경우 해결 방법 : 전자서명 준비하기 API 재호출 |
400 |
E2018 |
서명자 정보 가져오기 API를 연속해서 2회 이상 호출하는 경우 해결 방법 : 전자서명 준비하기 API 재호출 |
400 |
E2019 |
전자서명 검증하기 API를 호출하기 전에 서명자 정보 가져오기 API를 호출하는 경우 해결 방법 : 전자서명 검증하기 API를 호출한 후에 서명자 정보 가져오기 API 호출 |
400 |
E3001 |
요청한 상품 코드에 대한 권한이 없는 경우 해결 방법: 이용 중인 상품에 대한 계약 내용 및 개발 가이드 확인 후 올바른 상품 코드로 재요청하거나 권한에 대해 문의 |
400 |
E3002 |
요청한 상품 코드가 존재하지 않는 경우 해결 방법: 이용 중인 상품에 대한 계약 내용 및 개발 가이드 확인 후 올바른 상품 코드로 재요청 |
400 |
E3003 |
요청 파라미터에 대한 계약 내용이 존재하지 않는 경우 해결 방법: 계약 내용 확인, 계약을 체결하지 않았다면 계약 체결 |
400 |
E3004 |
CI 습득 권한이 없는 이용기관이 전자서명 요청하기 API 요청 시 identify_items에 CI를 포함한 경우해결 방법: 딜러사에 문의해 권한 획득 후 재호출 |
400 |
E9001 |
이용기관의 IP가 시스템에 등록되지 않은 경우 해결 방법: 딜러사를 통해 IP 등록 요청(개발 IP와 운영 IP 모두 요청 필수) |
403 |
카카오톡 인증 표준창
| 코드 | 설명 |
|---|---|
E0001 |
서버 내부에서 처리 중 에러가 발생한 경우 해결 방법: 인증 표준창 호출하기 API를 새로 호출 |
E1001 |
필수 파라미터를 포함하지 않은 경우, 또는 파라미터의 데이터 타입이 적절하지 않거나 허용된 범위를 벗어난 경우 해결 방법: 요청 파라미터 확인 카카오톡에 연결된 번호가 해외 번호인 경우 해결 방법: 카카오톡에 연결된 번호 확인 |
E1002 |
해당 API에 대한 요청 권한이 없거나 요청 정보가 잘못된 경우 해결 방법: REST API 레퍼런스 에러 코드의 코드별 해결 방법 수행 |
E1004 |
헤더에 포함된 JWT가 없거나 잘못된 경우해결 방법: 올바른 딜러사 앱 JavaScript 키를 헤더에 포함해 재요청 |
E1005 |
잘못되거나 없는 settleId로 호출한 경우해결 방법: 올바른 settleId를 포함해 재요청 |
E1007 |
잘못된 페이즈의 settleId로 호출한 경우해결 방법: 요청 페이즈에 해당하는 올바른 settleId를 포함해 재요청 |
E1008 |
새로고침 또는 서명요청 허용 횟수를 초과한 경우 해결 방법: 인증 표준창 호출하기 API를 새로 호출 |
E2003 |
tx_id에 대한 정보가 존재하지 않는 경우해결 방법: 인증 표준창 호출하기 API를 재호출해 tx_id를 새롭게 발급받아 올바른 tx_id로 재요청 |
E2020 |
tx_id가 만료된 경우해결 방법: 인증 표준창 호출하기 API를 재호출해 tx_id를 새롭게 발급받아 올바른 tx_id로 재요청 |
E3002 |
요청한 상품 코드가 존재하지 않는 경우 해결 방법: 이용 중인 상품에 대한 계약 내용 및 개발 가이드 확인 후 올바른 상품 코드로 재요청 |
E3003 |
요청 파라미터에 대한 계약 내용이 존재하지 않는 경우 해결 방법: 계약 내용 확인, 계약을 체결하지 않았다면 계약 체결 |
E8001 |
스크립트 또는 기타 알 수 없는 오류 해결 방법: 인증 표준창 호출하기 API를 새로 호출 |
E8002 |
지원하지 않는 PC 또는 태블릿 브라우저 또는 모바일에서 접근을 시도한 경우 잘못된 URL로 접근을 시도한 경우 해결 방법: PC 또는 태블릿 환경인 경우 최신 브라우저 설치 후, 모바일 환경인 경우 PC나 태블릿에서 다시 시도 |
E8003 |
tx_id 발급 실패 후 접근을 시도한 경우해결 방법: 인증 표준창 호출하기 API를 재호출해 tx_id를 새롭게 발급받아 올바른 tx_id로 재요청 |
E8004 |
요청 유효 시간 만료 해결 방법: 인증 표준창 호출하기 API를 새로 호출 |
E8005 |
QR 인증의 2차 문자 인증을 2회 이상 실패한 경우 해결 방법: 인증 표준창 호출하기 API를 새로 호출 |
카카오톡 인증 로그인
에러 코드
이 문서는 카카오톡 인증 로그인 시에만 발생하는 에러에 대해 다룹니다. 이 외 카카오톡 인증 로그인 시 발생할 수 있는 에러는 카카오 로그인과 동일하며, 문제 해결에서 확인할 수 있습니다.
| 코드 | 설명 |
|---|---|
KOE116 |
이용기관 앱에 카카오톡 인증 로그인 사용 권한이 없는 경우 해결 방법: 제휴 계약 체결 |
KOE216 |
REST API 키로 카카오톡 인증 로그인을 요청한 경우 해결 방법: 카카오톡 인증 로그인은 Kakao SDK를 통한 요청만 지원하므로, 각 플랫폼에 해당하는 앱 키를 사용해 재요청 |
KOE217 |
카카오톡 인증 시 에러가 발생한 경우 해결 방법: error_description에 포함된 에러 코드 값을 카카오톡 인증에서 확인 후 조치 |
참고: 기타 에러
| 에러 | 해결 방법 |
|---|---|
| 해당 카카오계정에 연결된 카카오톡 없음 (EX: 카카오톡을 이용하지 않는 사용자, 또는 카카오톡에 로그인된 카카오계정과 다른 카카오계정으로 카카오톡 인증 로그인을 요청한 경우) |
카카오계정에 연결된 카카오톡이 없을 경우 카카오톡 인증 로그인을 이용할 수 없음을 사용자에게 안내 |
| 카카오톡 인증 로그인 요청이 만료됨 | 카카오톡 인증 로그인 요청은 5분의 유효일시가 적용되며, 요청이 만료되었다면 재요청해야 함error 및 error_description을 확인해 재요청 또는 로그인 페이지를 출력하도록 처리 |
| 이미 카카오톡 인증 로그인이 완료된 경우 | 이미 완료된 요청의 응답으로 전달된 토큰 및 tx_id 값을 확인하고 사용하거나, 올바르게 응답을 받아 처리하지 못했다면 재요청해야 함 |
| 카카오톡 버전에 의해 발생하는 에러 | 카카오톡 인증 로그인을 사용하려면 10.0.0 이상의 카카오톡이 필요함을 사용자에게 안내 |
| 인증 요청 실패 인증 요청을 보낼 이용기관 채널을 사용자가 차단한 경우 "알림톡이 차단되어 인증을 진행할 수 없습니다. 채널 채팅방 상단에 알림톡 받기로 변경해주세요." 에러 문구 출력 |
사용자가 해당 채널 채팅방 상단에서 차단을 해제하도록 안내 |
카카오톡 축약서명
Kakao SDK로 카카오톡 축약서명 이용 시 발생할 수 있는 에러 정보입니다.
Android
| 에러 | 설명 |
|---|---|
ApiErrorCause.SigningIsNotCompleted |
인증 로그인 요청하기를 통한 사용자의 전자서명이 완료되지 않은 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 인증 로그인 완료 후 재시도 |
ApiErrorCause.InvalidTransaction |
인증 로그인 요청하기 후 전자서명 유효시간(5분) 안에 서명이 완료되지 않은 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 인증 로그인 완료 후 재시도 |
ApiErrorCause.TransactionHasExpired |
공개 키 유효시간이 만료된 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 임시 키 쌍 삭제하기로 임시 키 쌍과 세션 정보를 삭제하고, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 |
ClientErrorCause.IllegalState |
임시 키 쌍이 생성되지 않았거나, 세션이 유효하지 않거나, 세션이 만료된 상태에서 축약서명하기를 요청한 경우msg로 정확한 원인 확인해결 방법: 임시 키 쌍이 생성되지 않은 경우, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 세션이 유효하지 않은 경우, 세션 정보 가져오기 후 재시도 세션이 만료된 경우, 임시 키 쌍 삭제하기로 임시 키 쌍과 세션 정보를 삭제하고, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 |
iOS
| 에러 | 설명 |
|---|---|
ApiFailureReason.SigningIsNotCompleted |
인증 로그인 요청하기를 통한 사용자의 전자서명이 완료되지 않은 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 인증 로그인 완료 후 재시도 |
ApiFailureReason.InvalidTransaction |
인증 로그인 요청하기 후 전자서명 유효시간(5분) 안에 서명이 완료되지 않은 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 인증 로그인 완료 후 재시도 |
ApiFailureReason.TransactionHasExpired |
공개 키 유효시간이 만료된 상태에서 세션 정보 가져오기를 요청한 경우 해결 방법: 임시 키 쌍 삭제하기로 임시 키 쌍과 세션 정보를 삭제하고, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 |
ClientFailureReason.IllegalState |
임시 키 쌍이 생성되지 않았거나, 세션이 유효하지 않거나, 세션이 만료된 상태에서 축약서명하기를 요청한 경우message로 정확한 원인 확인해결 방법: 임시 키 쌍이 생성되지 않은 경우, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 세션이 유효하지 않은 경우, 세션 정보 가져오기 후 재시도 세션이 만료된 경우, 임시 키 쌍 삭제하기로 임시 키 쌍과 세션 정보를 삭제하고, 다시 처음부터 인증 로그인 과정을 거친 후 재시도 |
상태 확인 API
카카오톡 인증 서비스 API 호출이 가능한 상태인지 확인이 필요한 경우, 아래 API를 호출합니다. 정상 상태인 경우, 카카오톡 인증 서비스는 pong으로 응답합니다.
curl -v -G GET "https://cert-sign.kakao.com/api/ping"