페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • 문제 해결

카카오 로그인

문제 해결

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

인가 코드 관련 에러

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

에러 설명 해결 방법
KOE001 잘못된 형식의 요청인 경우 요청에 포함된 파라미터를 확인한 후 재요청합니다.
KOE002 잘못된 URL로 요청을 보낸 경우 요청을 보낸 URL을 확인 후 재요청합니다.
KOE003 카카오 OAuth 서버에서 일시적인 오류가 발생한 경우 잠시 후 재요청합니다.
문제가 지속될 경우 데브톡으로 문의합니다.
KOE004 카카오 로그인을 사용하도록 설정하지 않은 경우 [내 애플리케이션] > [카카오 로그인]에서 카카오 로그인 기능을 활성화합니다.

참고: 카카오 로그인 활성화 설정
KOE005 테스트 앱에 팀원으로 등록되지 않은 사용자가 로그인을 시도한 경우 [내 애플리케이션] > [팀 관리]에서 팀원을 추가합니다.

참고: 팀 관리
KOE006 등록하지 않은 Redirect URI를 사용해 인가 코드를 요청한 경우 [내 애플리케이션] > [카카오 로그인]에서 Redirect URI를 새로 등록하거나, 등록된 Redirect URI를 인가 코드 요청 redirect_uri 값으로 사용합니다.

참고: Redirect URI 등록
KOE007 등록하지 않은 Logout Redirect URI를 사용해 로그아웃을 요청한 경우 [내 애플리케이션] > [카카오 로그인] > [고급]에서 Logout Redirect URI를 새로 등록하거나, 등록된 Logout Redirect URI를 로그아웃 요청 logout_redirect_uri 값으로 사용합니다.

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

참고: 앱 키
KOE023 JavaScript SDK 팝업 방식으로 로그인 사용이 불가능한 경우 Kakao.Auth.authorize 함수를 사용하거나 JavaScript SDK를 최신버전으로 업데이트
KOE101 잘못된 앱 키를 사용한 경우 [내 애플리케이션] > [앱 키]에서 발급받은 앱 키를 올바르게 사용했는지 확인합니다.

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

Required PLUS_FRIENDS_ON_AGREEMENT_SUPPORTED permission		 카카오톡 채널과 앱을 연결한 후 재요청합니다.
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		 앱에 설정하지 않은 카카오 로그인 동의항목을 포함해 인가 코드를 요청한 경우

설정하지 않은 동의항목: ${SCOPE_ID}		 [내 애플리케이션] > [카카오 로그인] > [동의항목]에서 설정하지 않은 동의항목을 제외하고 재요청합니다.

참고: 동의항목 설정
KOE207
invalid_request		 필수 파라미터가 누락된 경우 REST API 문서에서 필수 파라미터를 확인한 후, 해당 파라미터를 포함하여 재요청합니다.
access_denied User denied access 사용자가 로그인을 취소했습니다. 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다.
access_denied Not allowed under age 14 만 14세 미만 사용자가 이용할 수 없는 앱이거나, 만 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 terms of service.		 카카오톡에서 자동 로그인 기능을 사용할 수 없습니다. 카카오 로그인으로 서비스에 직접 로그인해야 합니다.
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 파라미터 값이 서로 다른 앱의 앱 키인 경우 동일한 앱에서 발급받은 인가코드를 사용해 토큰을 재요청합니다.
KOE303
invalid_grant		 인가 코드 요청과 액세스 토큰 요청 시 사용한 redirect_uri가 서로 다른 경우

Redirect 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 잘못된 요청인 경우 요청 시 올바른 인자를 전달했는지 확인합니다.

OpenID Connect 관련 에러

  • 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 토큰의 만료 시간은 함께 발급된 액세스 토큰과 동일합니다.

Android

다음은 Android SDK를 통해 카카오 로그인 구현 시 발생할 수 있는 에러 목록입니다.

AuthErrorCause

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

ClientErrorCause

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

배송지

Kakao SDK로 배송지 요청 시 발생할 수 있는 문제의 해결 방법을 제공합니다. 배송지 가져오기 API 요청 시 발생하는 에러 정보는 레퍼런스를 참고합니다.

에러 코드

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

사용자 동의

배송지를 제공받으려면 사용자가 카카오 로그인 시 [배송지 정보] 동의항목에 동의해야 합니다. 사용자가 [배송지 정보] 동의항목에 동의하지 않았다면 배송지 기능이 아래와 같이 동작합니다.

배송지 가져오기 응답에 배송지가 포함되지 않은 경우

REST API 또는 JavaScript SDK를 사용해 배송지 가져오기 API 요청 시, 아래 예제와 같이 성공 응답에 배송지 상세 정보인 shipping_addresses 필드가 포함되지 않은 경우가 발생할 수 있습니다.

{
  "user_id": 143458,
  "shipping_addresses_needs_agreement": true
}

이 경우, shipping_addresses_needs_agreement 필드의 값을 확인해 다음과 같이 조치합니다.

  • true: 사용자가 [배송지 정보] 동의항목에 동의하지 않은 경우, 사용자 동의 시 정보 제공 가능 여부와 추가 항목 동의 받기로 사용자 동의 획득 후 재요청
  • false: 배송지 상세 정보를 제공받을 수 없는 경우
    • 배송지 ID가 유효하지 않은 경우: 배송지 선택하기 API로 올바른 배송지 ID 획득 후 재요청
    • 사용자가 배송지 제공에 동의했으나 배송지 정보가 없어 제공 불가, 서비스에서 직접 배송지를 입력받아야 함
카카오 로그인> 문제 해결