간편한 참조

REST API를 위한 모든 HTTP 요청의 경우 SSL환경의 HTTPS를 이용합니다. 로그인을 하기위해서는 REST API 키가 필요하고, 로그인 후 API 요청들은 로그인시 발급 받은 토큰이 필요합니다.

REST API

다음은 REST API에서 지원되는 기능입니다.

사용자 관리
URL HOST METHOD 기능
/oauth/authorize https://kauth.kakao.com GET 로그인-코드받기
/oauth/token https://kauth.kakao.com POST 로그인-토큰받기, 로그인-토큰갱신
/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/me https://kapi.kakao.com GET/POST 사용자 정보 요청
/v1/user/update_profile https://kapi.kakao.com POST 사용자 정보 저장
/v1/user/ids https://kapi.kakao.com GET/POST 사용자 ID 리스트 요청
/v1/user/access_token_info https://kapi.kakao.com GET 토큰 유효성 검사 및 정보 얻기


카카오톡
URL HOST METHOD 기능
/v1/api/talk/profile https://kapi.kakao.com GET 프로필 요청
/v1/api/talk/memo/send https://kapi.kakao.com POST 나에게 보내기


카카오페이
URL HOST METHOD 기능
/v1/payment/ready https://kapi.kakao.com POST 결제준비-단건결제, 결제준비-정기결제
/v1/payment/approve https://kapi.kakao.com POST 결제승인
/v1/payment/subscription https://kapi.kakao.com POST 정기결제-2회차이후
/v1/payment/status https://kapi.kakao.com POST 결제상태조회
/v1/payment/cancel https://kapi.kakao.com POST 결제취소
/v1/payment/manage/subscription/status https://kapi.kakao.com POST 정기결제 상태조회
/v1/payment/manage/subscription/inactive https://kapi.kakao.com POST 정기결제 비활성화
/v1/payment/manage/report https://kapi.kakao.com POST 결제내역조회


카카오스토리
URL HOST METHOD 기능
/v1/api/story/isstoryuser https://kapi.kakao.com GET 사용자 확인
/v1/api/story/profile https://kapi.kakao.com GET 프로필 요청
/v1/api/story/post/note https://kapi.kakao.com POST 글 포스팅
/v1/api/story/upload/multi https://kapi.kakao.com POST 사진 업로드
/v1/api/story/post/photo https://kapi.kakao.com POST 사진 포스팅
/v1/api/story/linkinfo https://kapi.kakao.com GET 링크 정보 얻기
/v1/api/story/post/link https://kapi.kakao.com POST 링크 포스팅
/v1/api/story/mystory https://kapi.kakao.com GET 하나의 내스토리 정보 요청
/v1/api/story/mystories https://kapi.kakao.com GET 복수개의 내스토리 정보 요청
/v1/api/story/delete/mystory https://kapi.kakao.com DELETE 내스토리 삭제


푸시 알림
URL HOST METHOD 기능
/v1/push/register https://kapi.kakao.com POST 푸시 토큰 등록
/v1/push/tokens https://kapi.kakao.com GET 푸시 토큰 조회
/v1/push/deregister https://kapi.kakao.com POST 푸시 토큰 삭제
/v1/push/send https://kapi.kakao.com POST 푸시 알림 보내기


검색
URL HOST METHOD 기능
/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 블로그 검색
/v2/search/tip https://dapi.kakao.com GET 팁 검색
/v2/search/book https://dapi.kakao.com GET 책 검색
/v2/search/cafe https://dapi.kakao.com GET 카페 검색


로컬
URL HOST METHOD 기능
/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 카테고리로 장소 검색

응답 코드

REST API 호출을 통해 HTTP의 상태 코드 및 실행 결과에 따른 다양한 에러 코드가 존재합니다.

HTTP 상태 코드

다음은 응답에 대한 HTTP의 상태 코드 입니다. 대부분의 요청의 경우 HTTP 상태 코드와 함께 응답 바디를 포함하며, 요청 실패시 응답 바디의 에러 코드를 참고할 수 있습니다.

상태 코드 설명 비고
200 성공 응답 바디(Response Body)의 경우 각 API별로 틀릴 수 있음
400 실패 일반적인 오류. 주로 API에 필요한 필수 파라미터와 관련
401 실패 인증 오류. 주로 사용자 토큰과 관련
403 실패 권한/퍼미션등의 오류
500 실패 시스템 오류
502 실패 시스템 오류
503 실패 서비스 점검중

호출 성공의 경우 각각의 API별 응답 바디(Response Body)의 형식이 다를 수 있으므로, 자세한 내용은 각 API별 상세 설명을 참고하세요.

에러 코드

호출 실패시 HTTP 상태 코드외에 JSON 형식의 에러 코드 및 원인을 메시지로 받을 수 있습니다.

상세 코드

다음은 에러 코드에 대한 정의입니다. 값은 모두 음수로 표현됩니다.

code 설명 HTTP 상태 코드
-1 내부 처리 오류. 에러 코드로 상세 분류되어 있지 않은 경우 400
-2 잘못된 파라미터. 호출 인자값이 잘못되었거나 필수 인자가 포함되지 않은 경우 400
-3 지원되지 않는 서비스 API에 대한 호출. 해당 앱의 호출된 API가 설정에서 off되어 있을 경우 400
-4 계정 제재 또는 특정 서비스에서 해당 사용자의 제재로 인해 API 호출이 금지된 경우 400
-5 해당 API에 대한 권한/퍼미션이 없는 경우 403
-10 허용된 요청 횟수가 초과된 경우. 자세한 내용은 쿼터 및 제한을 참고 400
-101 해당 앱에 연결이 되지 않은 사용자의 요청. 로그인 기반 API의 경우 앱 연결이 선행되어야 함 400
-102 이미 해당 앱에 연결된(가입/등록) 사용자가 재연결을 시도할 경우 400
-103 존재하지 않는 카카오계정에 대한 호출 400
-201 사용자 관리 API 호출시 파라미터가 부적절히 구성되었을 경우. 주로 개발자 웹사이트의 (내 애플리케이션 > 설정 > 사용자 관리)에서 사용자 정보의 설정과 요청의 파라미터가 불일치 할 경우 발생 400
-301 등록되지 않은 앱키의 요청 또는 존재하지 않는 앱으로의 요청 400
-401 사용자 토큰이 잘못되었을 경우. 주로 만료된 토큰에 대한 요청 401
-402 해당 API에 대한 사용자의 동의 퍼미션이 없는 경우 403
-403 등록되지 않은 사이트에서의 API 호출이 있을 경우 403
-501 카카오톡 미가입 사용자가 카카오톡 API를 호출 하였을 경우 400
-601 카카오스토리 미가입 사용자가 카카오스토리 API를 호출 하였을 경우 400
-602 카카오스토리 이미지 업로드시 최대 용량(현재 10MB)을 초과하였을 경우 400
-603 카카오스토리 이미지 업로드/스크랩 정보 요청시 타임아웃 발생 400
-604 카카오스토리에서 스크랩이 실패하였을 경우 400
-605 카카오스토리에 존재하지 않는 내스토리를 요청을 했을 경우 400
-606 카카오스토리 이미지 업로드시, 최대 이미지 갯수(현재 5개. 단, gif 파일은 1개)를 초과하였을 경우 400
-701 결제인증이 완료되지 않았는데 결제승인 API를 호출한 경우 400
-702 이미 결제 완료된 TID로 다시 결제승인 API를 호출한 경우 400
-703 결제승인 API 호출 시 포인트 금액이 잘못된 경우 400
-704 결제승인 API 호출 시 원결제수단(머니/카드)의 금액이 잘못된 경우 400
-705 결제승인 API 호출 시 지원하지 않는 결제수단으로 요청한 경우 400
-706 결제준비 API에서 요청한 partner_order_id 와 다른 값으로 결제승인 API 호출 한 경우 400
-707 결제준비 API에서 요청한 partner_user_id 와 다른 값으로 결제승인 API 호출 한 경우 400
-708 잘못된 pg_token 로 결제승인 API를 호출한 경우 400
-710 결제취소 API 호출 시 취소 요청 금액을 취소 가능액보다 큰 금액으로 요청한 경우 400
-721 TID가 존재하지 않는 경우 400
-722 금액 정보가 잘못된 경우 400
-723 결제 만료 시간이 지난 경우 400
-724 단건결제금액이 잘못된 경우 400
-725 총 결제금액이 잘못된 경우 400
-726 주문정보가 잘못된 경우 400
-730 가맹점 앱 정보가 잘못된 경우 400
-731 CID 가 잘못된 경우 400
-732 GID 가 잘못된 경우 400
-750 SID가 존재하지 않는 경우 400
-751 비활성화된 SID로 정기결제 API 를 호출한 경우 400
-752 SID가 월 최대 사용 횟수를 초과한 경우 400
-753 정기결제 API 호출시 partner_user_id가 SID를 발급받았던 최초 결제준비 API 에서 요청한 값과 다른 경우 400
-761 입력한 전화번호가 카카오톡에 가입하지 않은 경우 400
-780 결제승인 API 호출이 실패한 경우 400
-781 결제취소 API 호출이 실패한 경우 400
-782 정기결제 API 호출이 실패한 경우 400
-783 승인요청을 할 수 없는 상태에 결제승인 API를 호출한 경우 400
-784 취소요청을 할 수 없는 상태에 결제취소 API를 호출한 경우 400
-785 결제/취소를 중복으로 요청한 경우 400
-798 허용되지 않는 ip를 사용한 경우 400
-799 등록된 웹사이트 도메인의 설정과 요청 도메인이 다를 경우. 해당 서비스(앱/웹)의 사이트 도메인 설정이 필요합니다. 개발자 웹사이트내의 [내 애플리케이션]-[설정]-[일반]-[플랫폼]-[웹]의 설정을 살펴보세요. 400
-802 카카오톡 링크 사용시 등록된 웹사이트 도메인의 설정과 메시지내의 도메인이 다를 경우. 해당 서비스(앱/웹)의 사이트 도메인 설정이 필요합니다. 개발자 웹사이트내의 [내 애플리케이션]-[설정]-[일반]-[플랫폼]-[웹]의 설정을 살펴보세요. 400
-803 등록된 웹사이트 도메인 설정이 없는 경우. 해당 서비스(앱/웹)의 사이트 도메인 설정이 필요합니다. 개발자 웹사이트내의 [내 애플리케이션]-[설정]-[일반]-[플랫폼]-[웹]의 설정을 살펴보세요. 400
-901 등록된 푸시토큰이 없는 기기로 푸시 메시지를 보낸 경우 400
-9798 서비스 점검중 503
예제

다음은 호출 실패시의 에러 코드 및 메시지의 한 예입니다. code의 경우 Integer, msg의 경우 String 형식입니다.


  • API의 허용된 요청 횟수가 초과된 경우
{
  "code":-10,
  "msg":"API limit has been exceeded."
}
  • 사용자 토큰이 잘못되었을 경우
{
  "code":-401,
  "msg":"InvalidTokenException"
}

code 값의 경우 특별한 규칙을 가지고 있지 않으며, msg 값의 경우 의미가 바뀌지 않는 범위에서 내용이 바뀔 수 있습니다.


Last Modified : 2017-09-05