페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • 에러 코드

카카오 로그인

에러 코드

이 문서는 카카오 로그인 이용 중 발생할 수 있는 주요 에러와 해결 방법을 안내합니다.

이 외에 에러 코드는 공통 에러 코드를 참고합니다.

REST API

공통

카카오 로그인 API를 호출 시 발생할 수 있는 에러 목록입니다.

에러 코드 상태 코드 원인 해결 방법
-101 400 해당 앱에 카카오계정 연결이 완료되지 않은 사용자가 호출한 경우 카카오계정 연결 후 재시도
-102 400 이미 앱과 연결되어 있는 사용자의 토큰으로 수동 연결을 요청한 경우 -
-103 400 휴면 상태, 또는 존재하지 않는 카카오계정으로 요청한 경우 -
-201 400 사용자 정보 요청 API나 사용자 정보 저장 API 호출 시 앱에 추가하지 않은 사용자 프로퍼티 키 값을 불러오거나 저장하려고 한 경우 앱 관리 페이지의 [카카오 로그인] > [사용자 프로퍼티]에서 설정한 사용자 프로퍼티 키와 요청 파라미터가 일치하도록 설정
-402 403 해당 API에서 접근하는 리소스에 대해 사용자의 동의를 받지 않은 경우 응답본문의 required_scopes을 확인하여 사용자에게 해당 동의항목을 추가 동의 받도록 요청
-406 401 14세 미만 미허용 설정이 되어 있는 앱으로 14세 미만 사용자가 API 호출한 경우 -

인가 코드

카카오 로그인 인가 코드 발급 시 발생할 수 있는 에러 목록입니다.

에러 코드 원인 해결 방법
KOE001 잘못된 형식의 요청인 경우 요청에 포함된 파라미터를 확인한 후 재요청합니다.

참고: 인가 코드 요청
KOE002 잘못된 URL로 요청을 보낸 경우 요청을 보낸 URL을 확인 후 재요청합니다.

참고: 인가 코드 요청
KOE003 카카오 OAuth 서버에서 일시적인 오류가 발생한 경우 잠시 후 재요청합니다.
문제가 지속될 경우 데브톡으로 문의합니다.
KOE004 카카오 로그인을 사용하도록 설정하지 않은 경우 앱 관리 페이지의 [카카오 로그인]에서 카카오 로그인 기능을 활성화합니다.

참고: 카카오 로그인 사용 설정
KOE005 테스트 앱에 멤버로 등록되지 않은 사용자가 로그인을 시도한 경우 앱 관리 페이지의 [앱] > [멤버]에서 멤버를 추가합니다.

참고: 멤버
KOE006 등록하지 않은 리다이렉트 URI를 사용해 인가 코드를 요청한 경우 앱 관리 페이지의 [카카오 로그인]에서 리다이렉트 URI를 새로 등록하거나, 등록된 리다이렉트 URI를 인가 코드 요청 redirect_uri 값으로 사용합니다.

참고: 리다이렉트 URI
KOE007 등록하지 않은 로그아웃 리다이렉트 URI를 사용해 로그아웃을 요청한 경우 앱 관리 페이지의 [카카오 로그인] > [고급]에서 로그아웃 리다이렉트 URI를 새로 등록하거나, 등록된 로그아웃 리다이렉트 URI를 로그아웃 요청 logout_redirect_uri 값으로 사용합니다.

참고: 로그아웃 리다이렉트 URI
KOE008 인가 코드 요청에 잘못된 앱 타입을 사용한 경우 개발 환경에 맞는 타입의 앱 키(네이티브 앱 키, REST API 키, JavaScript 키 중 하나)를 사용해 재요청합니다.

참고: 앱 키
KOE023 JavaScript SDK 팝업 방식으로 로그인 사용이 불가능한 경우 Kakao.Auth.authorize 함수를 사용하거나 JavaScript SDK를 최신버전으로 업데이트합니다.

참고: JavaScript 개발 문서, JavaScript 설치
KOE101 잘못된 앱 키를 사용한 경우 앱 관리 페이지의 [앱] > [일반] > [앱 키]에서 발급받은 앱 키를 올바르게 사용했는지 확인합니다.

참고: 앱 키
KOE102
invalid_client		 카카오톡 채널과 연결되지 않은 앱으로 인가 코드 요청 시 channel_public_id 파라미터를 포함한 경우

에러 메시지: Required PLUS_FRIENDS_ON_AGREEMENT_SUPPORTED permission		 카카오톡 채널과 앱을 연결한 후 재요청합니다.

참고: 앱에 카카오톡 채널 연결
KOE125 카카오디벨로퍼스 앱 또는 개발자 계정이 제재된 경우 데브톡으로 문의합니다.
KOE201
invalid_request		 지원하지 않는 응답 유형(response_type)을 포함해 인가 코드를 요청한 경우

에러 메시지: Unsupported response type: ${response_type}		 response_type 파라미터 값을 code로 변경해 재요청합니다.

참고: 인가 코드 요청
KOE202
invalid_request		 response_type이 token일 경우

에러 메시지: Implicit grant Required OAUTH_IMPLICIT_GRANT_SUPPORTED permission		 response_type 파라미터 값을 code로 수정하고 재요청합니다.

참고: 인가 코드 요청
KOE203
invalid_request		 동의 화면에서 필수 동의항목에 동의하지 않은 경우

에러 메시지: All required service terms must be approved. required:${Service Term IDs} agreed:${Service Term IDs}		 비정상적 동의 과정에서 노출되는 에러 페이지입니다. 해당 페이지 노출 시 데브톡으로 문의합니다.
KOE204
invalid_request		 유효하지 않은 파라미터를 포함한 경우

에러 메시지: Invalid agreement_code: ${Agreement Code}		 사용할 수 있는 파라미터를 확인 후 재요청합니다.

참고: 인가 코드 요청
KOE205
invalid_scope		 앱에 설정하지 않은 카카오 로그인 동의항목을 포함해 인가 코드를 요청한 경우

에러 메시지: invalid_scope
설정하지 않은 동의항목: ${SCOPE_ID}		 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 설정하지 않은 동의항목을 제외하고 재요청합니다.

참고: 동의항목 설정
KOE207
invalid_request		 필수 파라미터가 누락된 경우 필수 파라미터를 확인한 후, 해당 파라미터를 포함하여 재요청합니다.

참고: 인가 코드 요청에서
access_denied 사용자가 로그인을 취소한 경우

에러 메시지: User denied access		 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다.
access_denied 만 14세 미만 사용자가 이용할 수 없는 앱이거나, 만 14세 미만 사용자의 보호자 동의에 실패한 경우

에러 메시지: Not allowed under age 14		 초기 화면으로 이동시키는 등의 조치가 필요합니다.
login_required 카카오계정 인증 필요
prompt=none을 사용해 카카오톡에서 자동 로그인을 요청했으나, 카카오톡에 연결된 카카오계정이 없는 경우

에러 메시지: user authentication required.		 카카오톡에서 자동 로그인 기능을 사용할 수 없습니다. 카카오 로그인으로 서비스에 직접 로그인해야 합니다.
consent_required 동의 화면으로 사용자 동의 필요
prompt=none을 사용해 카카오톡에서 자동 로그인을 요청했으나, 사용자가 아직 서비스 앱에 카카오 로그인한 적 없거나 동의해야 할 동의항목이 존재하는 경우

에러 메시지: user consent required.		 카카오톡에서 자동 로그인 기능을 사용할 수 없습니다. 카카오 로그인으로 서비스에 직접 로그인해야 합니다.
interaction_required prompt=none을 사용해 카카오톡에서 자동 로그인을 요청했으나, 사용자 정보 추가 제공 등 기타 사용자 동작이 필요한 경우

에러 메시지: need to collect additional personal information.		 카카오톡에서 자동 로그인 기능을 사용할 수 없습니다. 카카오 로그인으로 서비스에 직접 로그인해야 합니다.
interaction_required prompt=none을 사용해 카카오톡에서 자동 로그인을 요청했으나, 카카오계정 통합약관 동의가 필요한 사용자인 경우

에러 메시지: have to agree to kakao's service terms.		 카카오톡에서 자동 로그인 기능을 사용할 수 없습니다. 카카오 로그인으로 서비스에 직접 로그인해야 합니다.
interaction_required prompt=none을 사용해 카카오톡에서 자동 로그인을 요청했으나, 제재된 사용자인 경우

에러 메시지: account has been restricted.		 사용자가 카카오계정 제재 상태에 대한 안내 페이지를 볼 수 있도록, prompt=none을 제외하고 다시 인가 코드를 요청합니다.

참고: 자동 로그인

액세스 토큰

카카오 로그인 액세스 토큰 발급시 발생할 수 있는 에러 목록입니다.

에러 코드 원인 해결 방법
KOE101
invalid_client		 잘못된 앱 키 타입을 사용하거나 앱 키에 오타가 있을 경우

에러 메시지: Not exist client_id ${CLIENT_ID}		 앱 관리 페이지의 [앱] > [일반] > [앱 키]에서 발급받은 앱 키를 올바르게 사용했는지 확인합니다. Android, iOS SDK를 초기화할 때는 네이티브 앱 키를, JavaScript SDK를 초기화할 때는 JavaScript 키를, REST API를 호출할 때는 REST API 키를 사용해야 합니다.

참고: 앱 키
KOE009
misconfigured		 등록되지 않은 플랫폼에서 액세스 토큰을 요청한 경우

에러 메시지: invalid android_key_hash or ios_bundle_id or web_site_url		 앱 관리 페이지의 [앱] > [일반] > [플랫폼]에서 Web, Android, iOS 플랫폼 설정이 올바른지 확인합니다.

참고: 플랫폼 등록
KOE010
invalid_client		 클라이언트 시크릿(Client secret) 기능을 사용하는 앱에서 토큰 요청 시 client_secret 값을 누락했거나 잘못된 값을 전달한 경우

에러 메시지: Bad client credentials		 클라이언트 시크릿 기능을 활성화한 경우, client_secret 파라미터를 추가하지 않으면 OAuth 서버로부터 토큰을 발급받을 수 없습니다. 앱 관리 페이지의 [카카오 로그인] > [보안]에서 생성한 클라이언트 시크릿 코드를 client_secret 파라미터로 전달합니다.
KOE114
invalid_client		 인가 코드의 client_id와 토큰 요청의 client_id 파라미터 값이 서로 다른 앱의 앱 키인 경우 동일한 앱에서 발급받은 인가코드를 사용해 토큰을 재요청합니다.
KOE237
invalid_request		 요청 수 제한을 초과한 토큰 발급을 요청한 경우

에러 메시지: token request rate limit exceeded		 토큰별 역할과 만료 시간을 참고해 새로운 토큰이 필요한 시점에만 토큰 발급을 요청합니다.
KOE303
invalid_grant		 인가 코드 요청과 액세스 토큰 요청 시 사용한 redirect_uri가 서로 다른 경우

에러 메시지: 리다이렉트 URI mismatch.		 인가 코드 발급 요청 시 전달된 redirect_uri와 동일한 redirect_uri를 사용해 액세스 토큰을 요청합니다.
KOE310
invalid_request
unsupported_grant_type
invalid_grant		 grant_type 파라미터를 포함하지 않았거나, 지원하지 않는 값을 사용하는 경우 앱에서 사용할 수 있는 grant_type을 이용해 토큰을 재요청합니다.
KOE319
invalid_grant		 토큰 갱신 요청 시 리프레시 토큰을 전달하지 않은 경우

에러 메시지: refresh token is blank		 토큰 갱신 요청 시 발급받은 리프레시 토큰을 refresh_token 파라미터의 값으로 전달합니다.
KOE320
invalid_grant		 동일한 인가 코드를 두 번 이상 사용하거나, 이미 만료된 인가 코드를 사용한 경우, 혹은 인가 코드를 찾을 수 없는 경우

에러 메시지: authorization code not found for code=${AUTHORIZATION_CODE}		 액세스 토큰 요청 시, 매번 새로운 인가 코드를 사용해야 합니다. 인가 코드를 다시 발급한 후, 새로 발급받은 인가 코드로 액세스 토큰을 요청합니다.
KOE322
invalid_grant		 refresh_token을 찾을 수 없거나 이미 만료된 리프레시 토큰을 사용한 경우

에러 메시지: expired_or_invalid_refresh_token		 인가 코드를 사용하여 액세스 토큰과 리프레시 토큰을 새로 발급받습니다.
invalid_request 잘못된 요청인 경우 요청 시 올바른 인자를 전달했는지 확인합니다.

ID 토큰

OpenID Connect를 사용하는 앱에서 ID 토큰 관련 요청 시 발생할 수 있는 에러 목록입니다.

에러 코드 원인 해결 방법
KOE400
invalid_token		 ID 토큰 값이 전달되지 않았거나 올바른 형식이 아닌 ID 토큰인 경우

에러 메시지: invalid id_token format		 올바른 ID 토큰 값으로 재요청합니다.
KOE401
invalid_token		 ID 토큰을 발급한 인증 기관(iss)이 카카오 인증 서버(kauth.kakao.com)가 아닌 경우

에러 메시지: invalid id_token issuer		 올바른 ID 토큰 값으로 재요청합니다.

참고: 카카오 인증 서버가 발급한 ID 토큰의 iss 값은 https://kauth.kakao.com으로 고정입니다. iss 값이 다르면 카카오 로그인으로 발급된 유효한 ID 토큰이 아닙니다.
KOE402
invalid_token		 서명이 올바르지 않아 유효한 ID 토큰이 아닌 경우

에러 메시지: invalid id_token		 올바른 ID 토큰 값으로 재요청합니다.

참고: 카카오 인증 서버가 발급한 ID 토큰은 공개키를 사용해 서명의 유효성을 검증할 수 있습니다. ID 토큰 유효성 검증을 참고합니다.
KOE403
invalid_token		 만료된 ID 토큰인 경우

에러 메시지: id_token has expired		 올바른 ID 토큰 값으로 재요청합니다.

참고: ID 토큰의 만료 시간은 함께 발급된 액세스 토큰과 동일합니다.

배송지

Kakao SDK로 배송지 요청 시 발생할 수 있는 문제의 해결 방법을 제공합니다.

에러 코드 원인 해결 방법
KAE003
INVALID_PARAMETER_ERROR		 잘못된 파라미터 값을 사용한 경우 올바른 파라미터 값으로 재요청
KAE102
APP_SCOPE_ERROR		 앱에 배송지 동의항목이 설정되지 않음 동의항목을 참고해 [배송지 정보] 동의항목 설정
KAE103
PERMISSION_ERROR		 권한이 없는 앱에서 요청한 경우 [배송지 정보] 동의항목 설정을 위한 권한 획득, 동의항목 설정 후 재요청
KAE104
APP_KEY_TYPE_ERROR		 REST API 키 또는 어드민 키로 요청한 경우 네이티브 앱 키와 JavaScript 키 중 사용 중인 Kakao SDK 종류에 맞는 앱 키로 재요청
KAE108
BLOCKED_APP_ERROR		 카카오디벨로퍼스 앱 또는 개발자 계정이 제재된 경우 데브톡으로 문의합니다.
KAE201
AUTH_ERROR		 액세스 토큰이 유효하지 않은 경우 액세스 토큰 재발급 후, 해당 액세스 토큰으로 재요청
KAE202
NOT_REGISTERED_USER_ERROR		 앱과 연결이 완료되지 않은 상태의 사용자인 경우 수동 연결 API로 사용자를 앱과 연결한 후 재요청
KAE203
INVALID_SCOPE_ERROR		 배송지 동의 화면에서 사용자가 동의 취소 또는 이탈해 에러가 발생한 경우 재요청하거나, 동의항목 추가 동의 요청을 참고해 사용자 동의 획득 후 재요청
KAE205
LOGIN_REQUIRED_ERROR		 사용자 카카오계정이 제재 및 보호 상태인 경우 에러 코드를 확인해 사용자에게 안내

네이티브 앱

아래는 Android, iOS, Flutter SDK에서 카카오 로그인 요청 시 발생할 수 있는 에러입니다.

인증

카카오 로그인 요청 시 발생하는 에러입니다.

에러 코드 원인 해결 방법
InvalidRequest 잘못된 파라미터를 전달한 경우 요청 시 전달한 파라미터 값이 올바른지 확인합니다.
InvalidClient 잘못된 앱 키를 전달한 경우 Android 또는 iOS SDK 초기화 시 사용한 앱 키 값이 앱 관리 페이지의 [앱] > [일반] > [앱 키]의 네이티브 앱 키와 일치하는지 확인합니다.
JavaScript SDK를 사용하는 경우, JavaScript 키를 사용해야 합니다.
InvalidScope 잘못된 동의항목 ID를 전달한 경우 scopes 파라미터에 전달된 동의항목 ID가 올바른지 확인합니다.
InvalidGrant 리프레시 토큰이 만료되었거나 존재하지 않는 경우 카카오 로그인으로 토큰을 새로 발급받습니다.
Misconfigured Android 플랫폼 설정이 올바르지 않은 경우 앱 관리 페이지의 [앱] > [일반] > [플랫폼] > [Android]의 패키지명, [카카오 로그인] 사용 여부 등 앱 설정이 올바른지 확인합니다.
Unauthorized 요청 권한이 없는 앱인 경우 카카오 로그인은 별도 권한 신청 없이도 사용할 수 있는 API입니다. 해당 에러 응답을 받은 경우 데브톡으로 문의합니다.
AccessDenied 사용자가 동의 화면에서 로그인을 취소한 경우 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다.
ServerError 일시적인 서버 오류가 발생한 경우 잠시 후 다시 요청합니다.
문제가 지속될 경우, 데브톡으로 문의합니다.
Unknown 알 수 없는 오류가 발생한 경우 에러 로그를 보고 문제를 파악합니다.
해결이 어려울 때는 데브톡으로 문의합니다.

클라이언트

SDK 내부에서 발생하는 클라이언트 에러입니다.

에러 코드 원인 해결 방법
NotSupported 지원하지 않는 기능인 경우
카카오톡 또는 사용 가능한 브라우저 앱이 설치되어 있지 않은 경우 발생합니다.		 사용자 기기에 사용 가능한 브라우저가 있는지 확인 후 카카오 로그인을 요청하거나, 카카오 로그인을 이용할 수 없는 환경임을 사용자에게 안내합니다.
Cancelled 사용자가 로그인 요청을 취소한 경우 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다.
TokenNotFound API 요청에 사용할 토큰이 없는 경우
카카오 로그인으로 발급받은 토큰이 필요한 API를 호출한 경우 발생합니다.		 카카오 로그인으로 토큰 발급 후 해당 API를 호출하도록 수정합니다.
BadParameter 잘못된 파라미터를 전달한 경우 요청 시 전달된 파라미터 값이 올바른지 확인합니다.
IllegalState 요청을 정상적으로 실행할 수 없는 상태인 경우 에러 로그를 보고 문제를 파악합니다.
해결이 어려울 때는 데브톡으로 문의합니다.
Unknown 알 수 없는 오류가 발생한 경우 에러 로그를 보고 문제를 파악합니다.
해결이 어려울 때는 데브톡으로 문의합니다.
카카오 로그인> 에러 코드