페이지 이동경로
  • 문서>
  • REST API>
  • 레퍼런스

REST API

레퍼런스

이 문서는 카카오 API 플랫폼에서 제공하는 REST API의 규격 정보를 안내합니다.

요청

카카오 플랫폼의 API 요청 규격을 구성하는 요소는 다음과 같습니다.

구성 요소 설명
메서드(Method) 카카오 API 호출 시 사용해야 할 HTTP 요청 메서드입니다.
(예: GET, POST, PUT, DELETE)
호스트(Host) 요청을 받는 카카오 API 서버의 도메인입니다.
(예: kapi.kakao.com)
URL API를 통해 제공되는 리소스마다 지정된 요청 경로입니다.
호스트와 함께 각 API의 엔드포인트(Endpoint)를 구성합니다.
(예: /v2/user/me)
헤더(Header) 카카오 API 호출 시 필요한 인증 정보(Authorization)나 기타 추가 정보를 전달하는 데 사용합니다.
인증 정보는 액세스 토큰 또는 앱 키를 사용합니다.
일부 카카오모먼트 API는 인증 정보와 함께 광고계정 ID를 헤더에 포함하여 호출해야 합니다.
(예: Authorization: Bearer ${ACCESS_TOKEN})
경로 변수(Path variable) 카카오 API 호출 시, 사용자가 전달한 값을 포함해 URL을 구성할 때 사용합니다.
카카오모먼트 등 일부 카카오 API는 URL에 경로 변수를 포함합니다.
(예: /openapi/v4/campaigns/${id})
파라미터(Parameter) 요청 처리에 필요한 데이터를 전달하는 데 사용합니다.
파라미터는 키와 값의 쌍으로 구성되며, 쿼리 스트링(Query string) 또는 본문을 통해 전달합니다.
각 파라미터는 자료형(Data type)과 필수 전달 여부가 지정돼 있습니다.

각 API의 요청 규격이 다르므로, API별 개발 가이드에서 상세 정보를 확인하고 호출해야 합니다. 요구 사양을 함께 참고합니다.

참고: 보안 설정

서비스의 필요에 따라 보안 강화 요소로 허용 IP 주소클라이언트 시크릿 코드(Client secret code) 설정을 사용할 수 있습니다.

응답

응답 형식

카카오 플랫폼은 API 요청에 대해 응답 코드와 응답 필드로 구성된 응답을 제공합니다. 응답 필드는 각 API의 호스트 및 요청 성공 여부에 따라 구성이 다릅니다.

  • 요청 성공 시: HTTP 상태 코드 및 API별 성공 응답 필드 반환
  • 요청 실패 시: HTTP 상태 코드 및 JSON 형식의 에러 응답 필드 반환, 에러 응답 필드에 에러 코드 및 메시지 포함

아래는 주요 호스트의 에러 응답 필드 구성 및 예시입니다.

kauth.kakao.com
이름 타입 설명 필수
error String 에러 코드
문제 해결에서 상세 정보 확인 가능
X
error_description String 실패 원인을 나타내는 에러 메시지
에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함
X
kapi.kakao.com
이름 타입 설명 필수
code Int 에러 코드 X
msg String 에러 메시지
에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함
X
예: 토큰이 잘못되었을 경우
HTTP/1.1 401 Unauthorized  
WWW-Authenticate: Bearer error=invalid_token
{
  "code":-401,
  "msg":"InvalidTokenException"
}
예: API의 허용된 요청 회수 초과
HTTP/1.1 400 Bad Request  
{
  "code":-10,
  "msg":"API limit has been exceeded."
}
예: 카카오톡 메시지 보내기 기능 접근 권한이 없어 전송 실패
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}
참고: 에러 코드와 에러 메시지

code는 특별한 규칙을 가지고 있지 않은 음수의 숫자이고, 실패 원인을 나타내는 msg는 요청에 따라 의미가 바뀌지 않는 범위에서 내용이 바뀔 수 있습니다. 예를 들어, code가 -401일 경우 전달되는 msg의 내용은 아래와 같이 다양하게 전달됩니다.

예: 유효하지 않은 앱키나 액세스 토큰으로 요청한 경우
"this access token does not exist", "this access token is already expired", "appKey(xxxxxxxx) is already deactivated"
예: [내 애플리케이션] > [플랫폼]에 등록된 도메인이 아닌 도메인에서 API를 호출한 경우
"domain mismatched! caller=xxxxxxxx. check out registered web domains."
예: [내 애플리케이션] > [플랫폼]에 등록된 정보와 클라이언트의 정보가 맞지 않을 경우
"android keyhash mismatched! caller=xxxxxxxx. check out registered keyhash."
"ios bundle id mismatched! caller=xxxxxxxx. check out registered bundle id."
예: [내 애플리케이션] > [허용 IP 주소] 설정에 해당하는 IP에서 요청하지 않았을 경우
"ip mismatched! callerIp=xxxxxxxx. check out registered ips."

응답 코드

응답 코드는 요청에 대한 상태를 나타내는 HTTP 상태 코드(Status code), 에러에 대한 정보를 담은 에러 코드(Error code)로 나뉩니다. 요청 성공 시 HTTP 상태 코드 200과 함께 요청에 대한 응답 본문(response body)이 반환되고, 요청이 실패한 경우 codemsg로 이루어진 에러 코드를 반환합니다.

HTTP 상태 코드

HTTP 상태 코드(HTTP Status code)란 응답 메시지의 첫 번째 줄에 나타나는 세 자리 숫자의 코드로 요청에 대한 상태 정보(성공 또는 실패)를 나타냅니다. 상태 코드는 크게 5가지로 분류되며, 상태 코드의 첫 번째 숫자로 응답의 종류를 파악할 수 있습니다. 자세한 정보는 RFC 2616을 참고합니다.

아래는 카카오 플랫폼이 API 요청에 대해 응답하는 상태 코드의 종류와 의미입니다.

상태 코드 상태 설명
200
OK
성공 서버가 클라이언트의 요청을 성공적으로 수행
응답 본문의 경우 각 API별로 응답 본문의 형식이 다를 수 있으므로, 자세한 내용은 각 API별 상세 설명을 참고합니다.
400
Bad Request
실패 일반적인 오류
주로 API에 필요한 필수 파라미터와 관련하여 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태입니다.
401
Unauthorized
실패 인증 오류(주로 토큰 관련)
해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태입니다.
응답은 OAuth 2.0 RFC6750 표준 규격에 따라 헤더에 오류 정보를 포함합니다.
토큰 사용 시: WWW-Authenticate: Bearer error=invalid_token
서비스 앱 어드민 키 사용 시: WWW-Authenticate: KakaoAK error=invalid_token
상세 오류 정보는 응답 본문에서 확인할 수 있습니다.
403
Forbidden
실패 권한 오류
서버에 요청이 전달되었지만, 권한 때문에 거절된 상태입니다.
429
Too Many Request
실패 쿼터 초과(Daum 검색, 로컬, 모먼트, 키워드광고 API에만 해당)
정해진 사용량이나 초당 요청 한도를 초과한 경우
500
Internal Server Error
실패 시스템 오류
서버 에러를 총칭하는 에러 코드로, 요청을 처리하는 과정에서 서버가 예상하지 못한 상황에 놓인 상태입니다.
502
Bad Gateway
실패 시스템 오류
서로 다른 프로토콜을 연결해주는 게이트웨이가 잘못된 프로토콜을 연결하거나 연결된 프로토콜에 문제가 있어 통신이 제대로 되지 않은 상태입니다.
503
Service Unavailable
실패 서비스 점검중
서버가 요청을 처리할 준비가 되지 않은 상태입니다.

에러 코드

아래는 카카오 API 제품별로 발생할 수 있는 에러 코드 정보입니다. 에러 발생 시 code 중 해당하는 항목을 찾아 원인을 파악합니다.

공통

코드 설명 HTTP 상태 코드
-1 서버 내부에서 처리 중에 에러가 발생한 경우
해결 방법: 재시도
400
-2 필수 인자가 포함되지 않은 경우나 호출 인자값의 데이타 타입이 적절하지 않거나 허용된 범위를 벗어난 경우
해결 방법: 요청 파라미터 확인
400
-3 해당 API를 사용하기 위해 필요한 기능(간편가입, 동의항목, 서비스 설정 등)이 활성화 되지 않은 경우
해결 방법: [내 애플리케이션]에서 필요한 기능을 선택한 후, [활성화 설정]에서 ON으로 설정한 후 재호출
403
-4 계정이 제재된 경우나 해당 계정에 제재된 행동을 하는 경우 403
-5 해당 API에 대한 요청 권한이 없는 경우
해결 방법: 해당 API의 이해하기 문서를 참고하여 검수 진행, 권한 획득 후 재호출
403
-7 서비스 점검 또는 내부 문제가 있는 경우
해결 방법: 해당 서비스 공지사항 확인
400
-8 올바르지 않은 헤더로 요청한 경우
해결 방법: 요청 헤더 확인
400
-9 서비스가 종료된 API를 호출한 경우
해결 방법: 공지 메일이나 데브톡 공지확인
400
-10 허용된 요청 회수를 초과한 경우
해결 방법: 쿼터 확인 후 쿼터 범위 내로 호출 조정, 필요시 데브톡으로 제휴 문의
400
-401 유효하지 않은 앱키나 액세스 토큰으로 요청한 경우, 등록된 앱 정보와 호출된 앱 정보가 불일치 하는 경우
해결 방법: 앱키 확인 또는 토큰 갱신, 개발자 사이트에 등록된 앱 정보 확인
401
-501 카카오톡 미가입 또는 유예 사용자가 카카오톡 또는 톡캘린더 API를 호출한 경우 400
-602 이미지 업로드 시 최대 용량을 초과한 경우 400
-603 카카오 플랫폼 내부에서 요청 처리 중 타임아웃이 발생한 경우 400
-606 업로드할 수 있는 최대 이미지 개수를 초과한 경우 400
-903 등록되지 않은 개발자의 앱키나 등록되지 않은 개발자의 앱키로 구성된 액세스 토큰으로 요청한 경우 400
-911 지원하지 않는 포맷의 이미지를 업로드 하는 경우 400
-9798 서비스 점검중 503

카카오 로그인

카카오 로그인 기반 일부 API의 경우 앱 연결이 선행되어야 합니다.

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

메시지

코드 설명 HTTP 상태 코드
-502 받는 이가 보내는 이의 친구가 아닌 경우
해결 방법: 친구 캐시(cache) 만료 시간 후에 재요청
400
-530 받는 이가 메시지 수신 거부를 설정한 경우 400
-532 특정 앱에서 보내는 이가 받는 사람 관계없이 하루 동안 보낼 수 있는 쿼터를 초과한 경우 400
-533 특정 앱에서 받는 이가 하루 동안 받을 수 있는 쿼터를 초과한 경우 400
-536 '보내는 이와 받는 이' 한 쌍을 기준으로 하루 동안 주고 받을 수 있는 쿼터를 초과한 경우 400

카카오톡 채널

코드 설명 HTTP 상태 코드
-541 존재하지 않는 카카오톡 채널인 경우 400
-544 카카오톡 채널이 제재 상태인 경우 400
-815 카카오톡 채널 API 내부 에러 400
-816 파일 ID가 잘못된 경우나 해당 파일 ID로 업로드된 카카오톡 채널 고객파일을 찾을 수 없는 경우 400
-817 이미 존재하는 파일명이나 허용되지 않는 파일명으로 고객파일 등록하는 경우 400
-818 등록한 고객파일이 최대 개수를 초과한 경우 (카카오톡 채널 관리자센터에 업로드한 파일 포함하여 최대 30개) 400
-819 카카오톡 채널과 앱이 연결되지 않은 경우
해결 방법: 카카오톡 채널과 앱 연결
400

푸시 알림

코드 설명 HTTP 상태 코드
-901 등록된 푸시 토큰이 없는 기기로 푸시 메시지를 보낸 경우 400

톡캘린더

코드 설명 HTTP 상태 코드
-520 공개 일정 ID 또는 캘린더 ID가 존재하지 않는 경우 400
-521 카카오톡 프로필 스티커에 등록된 할 일을 수정 또는 삭제 시도한 경우 400

인공지능

코드 설명 HTTP 상태 코드
-830 KoGPT, Karlo API 요청 시 서버에서 요청 처리 중 오류가 발생한 경우 500
-831 KoGPT, Karlo API 요청 시 일시적으로 요청이 급증해 서버의 처리 가능 용량을 초과한 경우 503

카카오모먼트

이 외 응답 코드는 카카오모먼트를 참고합니다.

코드 설명 HTTP 상태 코드
-813 카카오모먼트 API의 내부 에러 400

카카오 키워드광고

이 외 응답 코드는 카카오 키워드광고를 참고합니다.

코드 설명 HTTP 상태 코드
-820 카카오 키워드광고 API의 내부 에러 400

API 목록

카카오 플랫폼에서 REST API로 제공하는 API 목록과 기본적인 요청 규격 정보입니다.

카카오 로그인

URL 호스트 메서드 기능
/oauth/authorize https://kauth.kakao.com GET 인가 코드 받기
추가 항목 동의 받기
서비스 약관 선택해 동의 받기
카카오톡에서 자동 로그인
/oauth/token https://kauth.kakao.com POST 토큰 받기, 토큰 갱신하기
/.well-known/openid-configuration https://kauth.kakao.com GET OIDC: 메타데이터 확인하기
/.well-known/jwks.json https://kauth.kakao.com GET OIDC: 공개키 목록 조회하기
/oauth/tokeninfo https://kauth.kakao.com POST OIDC: ID 토큰 정보 보기
/v1/user/logout https://kapi.kakao.com POST 로그아웃
/v1/user/signup https://kapi.kakao.com POST 연결하기
/v1/user/unlink https://kapi.kakao.com POST 연결 끊기
/v1/user/access_token_info https://kapi.kakao.com GET 토큰 정보 보기
/v2/user/me https://kapi.kakao.com GET/POST 사용자 정보 가져오기
/v1/user/update_profile https://kapi.kakao.com POST 사용자 정보 저장하기
/v1/user/shipping_address https://kapi.kakao.com GET 배송지 가져오기
/v1/user/ids https://kapi.kakao.com GET/POST 사용자 목록 가져오기
/v2/app/users https://kapi.kakao.com GET 여러 사용자 정보 가져오기
/v2/user/scopes https://kapi.kakao.com GET 동의 내역 확인하기
/v2/user/revoke/scopes https://kapi.kakao.com POST 동의 철회하기
/v2/user/service_terms https://kapi.kakao.com GET 서비스 약관 동의 내역 확인하기
/v2/user/revoke/service_terms https://kapi.kakao.com POST 서비스 약관 동의 철회하기
/v1/oidc/userinfo https://kapi.kakao.com GET OIDC: 사용자 정보 가져오기

카카오톡 소셜

URL 호스트 메서드 기능
/v1/api/talk/profile https://kapi.kakao.com GET 프로필 가져오기
/v1/api/talk/friends https://kapi.kakao.com GET 친구 목록 가져오기

메시지

URL 호스트 메서드 기능
/v2/api/talk/memo/default/send https://kapi.kakao.com POST 나에게 기본 템플릿으로 메시지 보내기
/v2/api/talk/memo/send https://kapi.kakao.com POST 나에게 사용자 정의 템플릿으로 메시지 보내기
/v2/api/talk/memo/scrap/send https://kapi.kakao.com POST 나에게 기본 템플릿으로 스크랩 메시지 보내기,
나에게 사용자 정의 템플릿으로 스크랩 메시지 보내기
/v1/api/talk/friends/message/default/send https://kapi.kakao.com POST 친구에게 기본 템플릿으로 보내기
/v1/api/talk/friends/message/send https://kapi.kakao.com POST 친구에게 사용자 정의 템플릿으로 보내기
/v1/api/talk/friends/message/scrap/send https://kapi.kakao.com POST 친구에게 기본 템플릿으로 스크랩 메시지 보내기,
친구에게 사용자 정의 템플릿으로 스크랩 메시지 보내기

카카오톡 채널

URL 호스트 메서드 기능
/v2/api/talk/channels https://kapi.kakao.com GET 카카오톡 채널 관계 확인하기
/v2/api/talk/channels/multi https://kapi.kakao.com GET 여러 사용자 카카오톡 채널 관계 확인하기
/v1/talkchannel/create/target_user_file https://kapi.kakao.com POST 고객 관리: 파일 등록하기
/v1/talkchannel/target_user_file https://kapi.kakao.com GET 고객 관리: 파일 보기
/v1/talkchannel/update/target_users https://kapi.kakao.com POST 고객 관리: 사용자 추가하기
/v1/talkchannel/delete/target_users https://kapi.kakao.com POST 고객 관리: 사용자 삭제하기

카카오모먼트

카카오모먼트 API 레퍼런스를 참고합니다.

카카오 키워드광고

카카오 키워드광고 API 레퍼런스를 참고합니다.

푸시 알림

URL 호스트 메서드 기능
/v2/push/register https://kapi.kakao.com POST 푸시 토큰 등록하기
/v2/push/tokens https://kapi.kakao.com GET 푸시 토큰 보기
/v2/push/deregister https://kapi.kakao.com POST 푸시 토큰 삭제하기
/v2/push/send https://kapi.kakao.com POST 푸시 알림 보내기

톡캘린더

URL 호스트 메서드 기능
/v2/api/calendar/calendars https://kapi.kakao.com GET 사용자 캘린더 > 목록 가져오기
/v2/api/calendar/create/calendar https://kapi.kakao.com POST 사용자 캘린더 > 생성하기: 서브 캘린더
/v2/api/calendar/update/calendar https://kapi.kakao.com POST 사용자 캘린더 > 수정하기: 서브 캘린더
/v2/api/calendar/delete/calendar https://kapi.kakao.com DELETE 사용자 캘린더 > 삭제하기: 서브 캘린더
/v2/api/calendar/create/event https://kapi.kakao.com POST 일반 일정 > 생성하기
/v2/api/calendar/events https://kapi.kakao.com GET 일반 일정 > 목록 가져오기
/v2/api/calendar/event https://kapi.kakao.com GET 일반 일정 > 상세 조회하기
/v2/api/calendar/update/event/host https://kapi.kakao.com POST 일반 일정 > 수정하기
/v2/api/calendar/delete/event https://kapi.kakao.com DELETE 일반 일정 > 삭제하기
/v2/api/calendar/public/create/event https://kapi.kakao.com POST 공개 일정 > 생성하기
/v2/api/calendar/public/events https://kapi.kakao.com GET 공개 일정 > 목록 가져오기
/v2/api/calendar/public/event https://kapi.kakao.com GET 공개 일정 > 상세 조회하기
/v2/api/calendar/public/update/event https://kapi.kakao.com POST 공개 일정 > 수정하기
/v2/api/calendar/public/delete/event https://kapi.kakao.com DELETE 공개 일정 > 삭제하기
/v2/api/calendar/public/follow https://kapi.kakao.com POST 공개 일정 > 사용자 캘린더에 추가하기
/v2/api/calendar/subscribable/calendars https://kapi.kakao.com GET 구독 캘린더 > 구독 가능 캘린더 목록 가져오기
/v2/api/calendar/subscribe https://kapi.kakao.com POST 구독 캘린더 > 구독하기
/v2/api/calendar/unsubscribe https://kapi.kakao.com DELETE 구독 캘린더 > 구독 해제하기
/v2/api/calendar/update/event/guest https://kapi.kakao.com POST 게스트 일정 > 수정하기
/v2/api/calendar/holidays https://kapi.kakao.com GET 공휴일 및 주요 기념일 조회하기
/v1/api/calendar/create/task https://kapi.kakao.com POST 할 일 > 생성하기
/v1/api/calendar/tasks https://kapi.kakao.com GET 할 일 > 조회하기
/v1/api/calendar/task/records https://kapi.kakao.com GET 할 일 > 도전 기록 보기
/v1/api/calendar/update/task https://kapi.kakao.com POST 할 일 > 수정하기
/v1/api/calendar/complete/task https://kapi.kakao.com POST 할 일 > 완료 여부 설정하기
/v1/api/calendar/delete/task https://kapi.kakao.com DELETE 할 일 > 삭제하기

로컬

URL 호스트 메서드 기능
/v2/local/search/address.{format} https://dapi.kakao.com GET 주소 검색하기
/v2/local/geo/coord2regioncode.{format} https://dapi.kakao.com GET 좌표로 행정구역정보 받기
/v2/local/geo/coord2address.{format} https://dapi.kakao.com GET 좌표로 주소 변환하기
/v2/local/geo/transcoord.{format} https://dapi.kakao.com GET 좌표계 변환하기
/v2/local/search/keyword.{format} https://dapi.kakao.com GET 키워드로 장소 검색하기
/v2/local/search/category.{format} https://dapi.kakao.com GET 카테고리로 장소 검색하기

Daum 검색

URL 호스트 메서드 기능
/v2/search/web https://dapi.kakao.com GET 웹문서 검색하기
/v2/search/vclip https://dapi.kakao.com GET 동영상 검색하기
/v2/search/image https://dapi.kakao.com GET 이미지 검색하기
/v2/search/blog https://dapi.kakao.com GET 블로그 검색하기
/v3/search/book https://dapi.kakao.com GET 책 검색하기
/v2/search/cafe https://dapi.kakao.com GET 카페 검색하기

KoGPT

URL 호스트 메서드 기능
/v1/inference/kogpt/generation api.kakaobrain.com POST KoGPT에게 요청하기

Karlo

URL 호스트 메서드 기능
/v2/inference/karlo/t2i api.kakaobrain.com POST 이미지 생성하기
/v2/inference/karlo/upscale api.kakaobrain.com POST 이미지 확대하기
/v2/inference/karlo/variations api.kakaobrain.com POST 이미지 변환하기
/v2/inference/karlo/nsfw_checker api.kakaobrain.com POST NSFW 검사하기

사용자 편의 API

URL 호스트 메서드 기능
/v1/system/ips kapi.kakao.com GET 카카오 IP 목록 가져오기
/api/health/current api-status.kakao.com GET 현재 상태 확인하기
api/health/history api-status.kakao.com GET 이력 확인하기