이 문서는 카카오 로그인 이용 중 발생할 수 있는 주요 에러와 해결 방법을 안내합니다.
카카오 로그인 인가 코드 발급시 발생할 수 있는 에러 목록입니다.
에러 | 설명 | 해결 방법 |
---|---|---|
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 파라미터로 전달합니다. |
KOE114invalid_client |
인가 코드의 client_id 와 토큰 요청의 client_id 파라미터 값이 서로 다른 앱의 앱 키인 경우 |
동일한 앱에서 발급받은 인가코드를 사용해 토큰을 재요청합니다. |
KOE303 invalid_grant |
인가 코드 요청과 액세스 토큰 요청 시 사용한 redirect_uri 가 서로 다른 경우Redirect URI mismatch. |
인가 코드 발급 요청 시 전달된 redirect_uri 와 동일한 redirect_uri 를 사용하여 액세스 토큰을 요청합니다. |
KOE310invalid_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 | 잘못된 요청인 경우 | 요청 시 올바른 인자를 전달했는지 확인합니다. |
에러 | 설명 | 해결 방법 |
---|---|---|
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 SDK를 통해 카카오 로그인 구현 시 발생할 수 있는 에러 목록입니다.
AuthErrorCause
에 정의된 에러 목록으로, 카카오 로그인 요청 시 발생하는 에러에러 | 설명 | 해결 방법 |
---|---|---|
InvalidRequest |
잘못된 파라미터를 전달했습니다. | 요청 시 전달한 파라미터 값이 올바른지 확인합니다. |
InvalidClient |
잘못된 앱 키를 전달했습니다. | Android SDK 초기화 시 사용한 앱 키 값이 [내 애플리케이션] > [앱 키]의 네이티브 앱 키와 일치하는지 확인합니다. |
InvalidScope |
잘못된 동의항목 ID를 전달했습니다. | scopes 파라미터에 전달된 동의항목 ID가 올바른지 확인합니다. |
InvalidGrant |
리프레시 토큰이 만료되었거나 존재하지 않습니다. | 카카오 로그인을 통해 토큰을 새로 발급받습니다. |
Misconfigured |
Android 플랫폼 설정이 올바르지 않습니다. | [내 애플리케이션] > [플랫폼] > [Android]의 패키지명, [카카오 로그인] 사용 여부 등 앱 설정이 올바른지 확인합니다. |
Unauthorized |
요청 권한이 없는 앱입니다. | 카카오 로그인은 별도 권한 신청 없이도 사용할 수 있는 API입니다. 해당 에러 응답을 받은 경우 데브톡으로 문의합니다. |
AccessDenied |
사용자가 동의 화면에서 로그인을 취소했습니다. | 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다. |
ServerError |
일시적인 서버 오류가 발생했습니다. | 잠시 후 다시 요청합니다. 문제가 지속될 경우, 데브톡으로 문의합니다. |
Unknown |
알 수 없는 오류가 발생했습니다. | 에러 로그를 보고 문제를 파악합니다. 해결이 어려울 때는 데브톡으로 문의합니다. |
ClientErrorCause
에 정의된 에러 목록으로, Android SDK 내부에서 발생하는 클라이언트 에러에러 | 설명 | 해결 방법 |
---|---|---|
NotSupported |
지원하지 않는 기능입니다. 카카오톡 또는 사용 가능한 브라우저 앱이 설치되어 있지 않은 경우 발생합니다. |
사용자 기기에 사용 가능한 브라우저가 있는지 확인 후 카카오 로그인을 요청하거나, 카카오 로그인을 이용할 수 없는 환경임을 사용자에게 안내합니다. |
Cancelled |
사용자가 로그인 요청을 취소했습니다. | 로그인 이전 또는 초기 화면으로 이동시키는 등의 조치가 필요합니다. |
TokenNotFound |
API 요청에 사용할 토큰이 없습니다. 카카오 로그인을 통해 발급받은 토큰이 필요한 API를 호출한 경우 발생합니다. |
카카오 로그인을 통해 토큰 발급 후 해당 API를 호출하도록 수정합니다. |
BadParameter |
잘못된 파라미터를 전달했습니다. | 요청 시 전달된 파라미터 값이 올바른지 확인합니다. |
IllegalState |
요청을 정상적으로 실행할 수 없는 상태입니다. | 에러 로그를 보고 문제를 파악합니다. 해결이 어려울 때는 데브톡으로 문의합니다. |
Unknown |
알 수 없는 오류가 발생했습니다. | 에러 로그를 보고 문제를 파악합니다. 해결이 어려울 때는 데브톡으로 문의합니다. |
Kakao SDK로 배송지 요청 시 발생할 수 있는 문제의 해결 방법을 제공합니다. 배송지 가져오기 API 요청 시 발생하는 에러 정보는 레퍼런스를 참고합니다.
에러 코드 | 설명 |
---|---|
KAE003INVALID_PARAMETER_ERROR |
잘못된 파라미터 값을 사용한 경우 해결 방법: 올바른 파라미터 값으로 재요청 |
KAE102APP_SCOPE_ERROR |
앱에 배송지 동의항목이 설정되지 않음 해결 방법: 동의항목을 참고해 [배송지 정보] 동의항목 설정 |
KAE103PERMISSION_ERROR |
권한이 없는 앱에서 요청한 경우 해결 방법: [배송지 정보] 동의항목 설정을 위한 권한 획득, 동의항목 설정 후 재요청 |
KAE104APP_KEY_TYPE_ERROR |
REST API 키 또는 어드민 키로 요청한 경우 해결 방법: 네이티브 앱 키와 JavaScript 키 중 사용 중인 Kakao SDK 종류에 맞는 앱 키로 재요청 |
KAE201AUTH_ERROR |
액세스 토큰이 유효하지 않은 경우 해결 방법: 액세스 토큰 재발급 후, 해당 액세스 토큰으로 재요청 |
KAE202NOT_REGISTERED_USER_ERROR |
앱과 연결이 완료되지 않은 상태의 사용자인 경우 해결 방법: 연결하기 API로 사용자를 앱과 연결한 후 재요청 |
KAE203INVALID_SCOPE_ERROR |
배송지 동의 화면에서 사용자가 동의 취소 또는 이탈해 에러가 발생한 경우 해결 방법: 재요청하거나, 추가 항목 동의 받기를 참고해 사용자 동의 획득 후 재요청 |
KAE205LOGIN_REQUIRED_ERROR |
사용자 카카오계정이 제재 및 보호 상태인 경우 해결 방법: 에러 코드를 확인해 사용자에게 안내 |
배송지를 제공받으려면 사용자가 카카오 로그인 시 [배송지 정보] 동의항목에 동의해야 합니다. 사용자가 [배송지 정보] 동의항목에 동의하지 않았다면 배송지 기능이 아래와 같이 동작합니다.
shipping_addresses_needs_agreement
값이 true
이고 배송지 상세 정보가 응답에 포함되지 않음, 배송지 가져오기 응답에 배송지가 포함되지 않은 경우 참고REST API 또는 JavaScript SDK를 사용해 배송지 가져오기 API 요청 시, 아래 예제와 같이 성공 응답에 배송지 상세 정보인 shipping_addresses
필드가 포함되지 않은 경우가 발생할 수 있습니다.
{
"user_id": 143458,
"shipping_addresses_needs_agreement": true
}
이 경우, shipping_addresses_needs_agreement
필드의 값을 확인해 다음과 같이 조치합니다.
true
: 사용자가 [배송지 정보] 동의항목에 동의하지 않은 경우, 사용자 동의 시 정보 제공 가능 여부와 추가 항목 동의 받기로 사용자 동의 획득 후 재요청false
: 배송지 상세 정보를 제공받을 수 없는 경우