페이지 이동경로
  • Docs>
  • Reference Information>
  • REST API Reference

Reference Information

REST API Reference

This document provides the URL information required to make a request using a REST API and a list of response codes passed in response to your request.

Requirements

If you call the Kakao APIs through a REST API, your server and development environments must meet the following minimum versions:

Name Supported version
OS X Mavericks or higher
Windows Windows XP SP3 or higher
Java JRE 1.8.0_101 or higher
Browser Chrome 49 or higher
Firefox 50 or higher
Safari 10 or higher
Internet Explorer (IE) 9 or higher
Microsoft Edge 14 or higher
CentOS/RHEL ca-certificates-2015.2.4-65.0.1.el6_6.noarch or higher

* Notice: Replacing SSL certificates in Kakao Open API Platform

Supported APIs

Here are the lists of URLs, hosts, and methods required when making a request to use each function that the REST API supports.

When you make an HTTP request, you must use HTTPS to secure the connection between browsers and web servers using the Secure Sockets Layer (SSL). You need a REST API key for a login, and you need the access token issued once logged in to call the APIs that require a login.

Kakao Login

URL HOST METHOD Function
/oauth/authorize https://kauth.kakao.com GET Getting authorization code,
Requesting additional consent,
Getting consent to desired terms,
Auto-login from Kakao Talk
/oauth/token https://kauth.kakao.com POST Getting tokens,
Refreshing tokens
/v1/user/logout https://kapi.kakao.com POST Logout
/v1/user/signup https://kapi.kakao.com POST Manual signup
/v1/user/unlink https://kapi.kakao.com POST Unlink
/v1/user/access_token_info https://kapi.kakao.com GET Retrieving token information
/v2/user/me https://kapi.kakao.com GET/POST Retrieving user information
/v1/user/shipping_address https://kapi.kakao.com GET Retrieving shipping address
/v1/user/update_profile https://kapi.kakao.com POST Storing user information
/v1/user/ids https://kapi.kakao.com GET/POST Retrieving user list
/v2/app/users https://kapi.kakao.com GET Retrieving multiple user information
/v2/user/scopes https://kapi.kakao.com GET Retrieving consent details
/v2/user/revoke/scopes https://kapi.kakao.com POST Revoking consent
/v1/user/service/terms https://kapi.kakao.com GET Retrieving user agreed terms
/v1/user/signup https://kapi.kakao.com POST Manual signup
OpenID Connect
URL HOST METHOD Function
/.well-known/jwks.json https://kauth.kakao.com GET Getting public key
/.well-known/openid-configuration https://kauth.kakao.com GET Retrieving Discovery document
/v1/oidc/userinfo https://kapi.kakao.com GET Retrieving user information for OIDC
/oauth/tokeninfo https://kauth.kakao.com POST Getting ID token information

Kakao Talk Social

URL HOST METHOD Function
/v1/api/talk/profile https://kapi.kakao.com GET Retrieving Kakao Talk profile
/v1/api/talk/friends https://kapi.kakao.com GET Retrieving list of friends

Message

URL HOST METHOD Function
/v2/api/talk/memo/default/send https://kapi.kakao.com POST Sending me message with default template
/v2/api/talk/memo/send https://kapi.kakao.com POST Sending me message with custom template
/v2/api/talk/memo/scrap/send https://kapi.kakao.com POST Sending me scrap message with default template,
Sending me scrap message with custom template
/v1/api/talk/friends/message/default/send https://kapi.kakao.com POST Sending friends message with default template
/v1/api/talk/friends/message/send https://kapi.kakao.com POST Sending friends message with custom template
/v1/api/talk/friends/message/scrap/send https://kapi.kakao.com POST Sending friends scrap message with default template,
Sending friends scrap message with custom template

Kakao Story

URL HOST METHOD Function
/v1/api/story/isstoryuser https://kapi.kakao.com GET Validating Kakao Story user
/v1/api/story/profile https://kapi.kakao.com GET Retrieving Kakao Talk profile
/v1/api/story/post/note https://kapi.kakao.com POST Posting text story
/v1/api/story/post/photo https://kapi.kakao.com POST Posting photo story
/v1/api/story/post/link https://kapi.kakao.com POST Posting link story
/v1/api/story/mystory https://kapi.kakao.com GET Retrieving specified story
/v1/api/story/mystories https://kapi.kakao.com GET Retrieving multiple stories
/v1/api/story/delete/mystory https://kapi.kakao.com DELETE Deleting story
/v1/api/story/upload/multi https://kapi.kakao.com POST Uploading image
/v1/api/story/linkinfo https://kapi.kakao.com GET Scraping web page

Kakao Talk Channel

URL HOST METHOD Function
/v1/api/talk/channels https://kapi.kakao.com GET Checking Kakao Talk Channel relationship
/v1/talkchannel/create/target_user_file https://kapi.kakao.com POST Customer management: Register customer file
/v1/talkchannel/target_user_file https://kapi.kakao.com GET Customer management: View customer file
/v1/talkchannel/update/target_users https://kapi.kakao.com POST Customer management: Add user
/v1/talkchannel/delete/target_users https://kapi.kakao.com POST Customer management: Delete user

Kakao Pay

URL HOST METHOD Function
/v1/payment/ready https://kapi.kakao.com POST Preparing single payment,
Initial subscription payment
/v1/payment/approve https://kapi.kakao.com POST Approving single payment
/v1/payment/subscription https://kapi.kakao.com POST Second subscription payment request
/v1/payment/cancel https://kapi.kakao.com POST Canceling payments
/v1/payment/order https://kapi.kakao.com POST Viewing orders
/v1/payment/manage/subscription/status https://kapi.kakao.com POST Retrieving subscription status
/v1/payment/manage/subscription/inactive https://kapi.kakao.com POST Disabling subscription

Kakao Moment

Refer to Kakao Moment API reference.

Kakao Keyword Ad

Refer to Kakao Keyword Ad API reference. This document is available in Korean only.

Push Notification

URL HOST METHOD Function
/v2/push/register https://kapi.kakao.com POST Registering push token
/v2/push/tokens https://kapi.kakao.com GET Retrieving push token
/v2/push/deregister https://kapi.kakao.com POST Deleting push token
/v2/push/send https://kapi.kakao.com POST Sending push notifications

Daum Search

URL HOST METHOD Function
/v2/search/web https://dapi.kakao.com GET Web document search
/v2/search/vclip https://dapi.kakao.com GET Video search
/v2/search/image https://dapi.kakao.com GET Image search
/v2/search/blog https://dapi.kakao.com GET Blog search
/v3/search/book https://dapi.kakao.com GET Book search
/v2/search/cafe https://dapi.kakao.com GET Cafe search

Local

URL HOST METHOD Function
/v2/local/search/address.{format} https://dapi.kakao.com GET Address search
/v2/local/geo/coord2regioncode.{format} https://dapi.kakao.com GET Convert coordinates to administrative information
/v2/local/geo/coord2address.{format} https://dapi.kakao.com GET Convert coordinates to address
/v2/local/geo/transcoord.{format} https://dapi.kakao.com GET Convert coordinate system
/v2/local/search/keyword.{format} https://dapi.kakao.com GET Place search by keyword
/v2/local/search/category.{format} https://dapi.kakao.com GET Place search by category

Pose

URL HOST METHOD Function
/pose https://cv-api.kakaobrain.com POST Analyzing image
/pose/job https://cv-api.kakaobrain.com POST Analyzing video
/pose/job/{job_id} https://cv-api.kakaobrain.com GET Checking video analysis result

Response code

Response codes include an HTTP status code indicating the status of the request and an error code about the error information. If the request is successful, the response body is returned with a status code of 200. If failed, an error code with the code and msg is returned.

HTTP status code

The HTTP status code is a 3-digit integer in the first line of a response message, indicating the request result (success or failure). The status codes are classified into five, and the first digit of the status code defines the types of response. Refer to RFC 2616 to see more about HTTP status code.

Here is the list of HTTP status codes that the Kakao platform transmits when you request the Kakao APIs and the descriptions.

Status code Status Description
200
OK
Success Indicates that the server has received and processed the client's request successfully.
The format of the response body may differ depending on APIs. Refer to the detailed description of each API.
400
Bad Request
Fail General error
Indicates the state in which the server has detected a client error related to required parameters and cannot process the request.
401
Unauthorized
Fail Authorization error (mostly related to tokens)
Indicates that the request has failed because the client has no valid authorization credentials for the resource.

NOTE: As specified in OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC6750), the 401 errors include the WWW-Authenticate header field as follows:
- If access token is used,
   "WWW-Authenticate: Bearer error=invalid_token"
- If app admin key is used,
   "WWW-Authenticate: KakaoAK error=invalid_token"
invalid_token is fixed for 401 errors. Refer to the error response body to figure out the error in detail.
403
Forbidden
Fail Permission Error
Indicates that the server has received the client's request but rejected it because the client has no permission.
429
Too Many Request
Fail Quota exceeded (Only for Daum Search, Local, Pose, Moment, and Keyword Ad APIs)
Indicates that you have exceeded the quota limit or request the limit per second for the API.
500
Internal Server Error
Fail System error
500 refers to the class of server errors, indicating that the server is in an unexpected situation while processing the request.
502
Bad Gateway
Fail System error
Indicates that communication is not working properly because a gateway converts to another wrong protocol or has something wrong with the converting protocol.
503
Service Unavailable
Fail Undergoing maintenance
Indicates that the server is not ready to process the request.

Error code

If the request fails, the Kakao server returns an error code including code as an integer and msg as a string in the message body as a JSON format.

Example: Fail, Invalid token
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error=invalid_token

{
  "code":-401,
  "msg":"InvalidTokenException"
}
Example: Fail, Exceeding API quota limit
HTTP/1.1 400 Forbidden  
{
  "code":-10,
  "msg":"API limit has been exceeded."
}
Example: Fail, No permission to send Kakao Talk message
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"
  ]
}

The code passed in the error response message body is a negative integer without any specific rule. The msg, passed along with the code, indicates the cause of request failure and may be different depending on the requested APIs. For example, in the case of code is -401, different msg can be passed according to the APIs as follows:

If requesting with invalid app key or access token
"this access token does not exist", "this access token is already expired", "appKey(xxxxxxxx) is already deactivated"
If requesting API from domain not registered in [My Application] > [Platform]
"domain mismatched! caller=xxxxxxxx. check out registered web domains."
If client information does not match the one registered in [My Application] > [Platform]
"android keyhash mismatched! caller=xxxxxxxx. check out registered keyhash."
"ios bundle id mismatched! caller=xxxxxxxx. check out registered bundle id."
If requesting with IP address not registered in [My Application] > [Allowed Server IP Address]
"ip mismatched! callerIp=xxxxxxxx. check out registered ips."

Here are the lists of codes passed when your request is failed for each API that the Kakao platform provides. If an error occurs, check the code you received in the following table to figure out its cause.

Common

code Description HTTP status code
-1 If an error occurs while the server is internally processing.
Solution: Retry.
400
-2 If some required parameters are not included, or if the argument value has the wrong data type or is out of the acceptable range.
Solution: Check the request parameters.
400
-3 If the required function for the API, such as Simple Signup, Consent Items, services settings, etc.), is not activated.
Solution: Select [My application] > {SERVICE_NAME}, enable the function under the Activation Settings and then make a request again.
403
-4 If an account has been blocked, or if you request some actions that may cause the account to block. 403
-5 If you have no permission to request the API.
Solution: Request a review to use the API, and then make a request again.
403
-7 If the service is undergoing maintenance or has an internal problem.
Solution: Check the Notice on the service.
400
-8 If you request with the invalid header.
Solution: Check the request header.
400
-9 If you call the API that has been terminated its service.
Solution: Check the Notice mail or Notice.
400
-10 If you have exceeded the allowed quota limit.
Solution: Check the allowed quota limit and request an API less than the quota limit. Refer to Operating Policy and FAQ.
400
-401 If you call an API using an invalid app key or access token, or if the app you requested does not match the registered app information.
Solution: Check your app key in [My Application] or retrieve the expired tokens. Check the app information registered in [My Application].
401
-501 If a user who has not signed up for Kakao Talk calls the Kakao Talk messaging API. 400
-602 If the file size of the uploaded image exceeds the maximum size. 400
-603 If a timeout occurs while processing the request on the Kakao Platform. 400
-819 If a Kakao Talk Channel and a service app are not connected.
Solution: Connect your Kakao Talk Channel and your app in Kakao Business.
400
-903 If you request an API using an unregistered developer's app key or an access token that consists of an unregistered developer's app key. 400
-911 If you upload an image file with the unsupported format. 400
-9798 If the service is undergoing maintenance. 503

Kakao Login

To use login-based APIs, the Kakao Account of the object who uses the APIs must link with the service app.

Code Description HTTP status code
-101 If a user whose Kakao Account is not linked to your app makes a request.
Solution: Retry after linking the Kakao Account to the app through Kakao Login.
400
-102 If you request to link a user who is already linked to an app using the user's access token. 400
-103 If you request an API with an invalid Kakao Account. 400
-201 If you attempt to retrieve or store the key value of a user property not registered in your app when calling the Retrieving user information API or the Storing user information API.
Solution: Go to [My Application] > [Kakao Login] > [User Properties] to check what user properties you have registered, and add a new user properly or use the registered user property for the request parameter.
400
-402 If a user has not agreed to provide the user information (scope) that the API attempts to access.
Solution: Check the required_scopes in the response body, and request additional consent to the scope.
403
-406 If a user under age 14 calls the API from the app that does not allow the users under age 14. 401

Message

Code Description HTTP status code
-502 If the recipient is not the sender's friend.
Solution: Retry to make a request after cached data expires.
400
-530 If the recipient refuses to receive a message. 400
-531 If the sender requests to send a message after exceeding the quota limit, allowed to send a message to a specific recipient from a specific app during a day. 400
-532 If the sender requests to send a message after exceeding the quota limit allowed to send a message regardless of recipients from a specific app during a day. 400
-533 If exceeding the quota limit, allowed to receive a message from a specific app during a day. 400
-534 If exceeding the quota limit, allowed to receive a message from a specific app during a month. 400
-536 If exceeding the quota limit, allowed to send and receive a message between a sender and a recipient during a day. 400
-541 If the Kakao Talk Channel does not exist. 400

Kakao Story

code Description HTTP status code
-601 If a user who is not a Kakao Story user calls the API that is only allowed for Kakao Stroy users. 400
-604 If it fails to scrape in Kakao Story. 400
-605 If you request to retrieve my story that does not exist in Kakao Story. 400
-606 If exceeding the maximum number of images you can upload in Kakao Story. You can currently upload up to five images. (In case of a GIF file, only one image is allowed) 400
-608 If a user who is not a Kakao Story Channel user requests the Kakao Story Channel API. 400

Kakao Talk Channel customer file management

Code Description HTTP status code
-816 If you request an API using the wrong customer file ID, or if it fails to find the customer file ID among the uploaded Kakao Talk Channel customer files. 400
-817 If you request the Registering customer file API using the existing file name or unallowed file name. 400
-818 If exceeding the maximum number of the customer files you can register. You can upload up to 30 files including the files uploaded to the Kakao Talk Channel Admin Center. 400

Kakao Pay

This section is available in Korean only. Refer to the original Korean documentation.

Kakao Moment

Refer to Kakao Moment > Reference.

Kakao Keyword Ad

This section is available in Korean only. Refer to the original Korean documentation.

Push Notification

Code Description HTTP status code
-901 If you send a push notification to a device that does not have any registered push token. 400

Pose

Code Description HTTP status code
-824 If exceeding the request limit per second that Pose APIs allow. 429

Others: Kakao server internal error

Code Description HTTP status code
-812 Internal error related to Translation APIs occurs. 400
-813 Internal error related to Kakao Moment APIs occurs. 400
-814 Internal error related to Pose APIs occurs. 500
-815 Internal error related to Kakao Talk Channel's customer file management occurs. 400
-820 Internal error related to Kakao Keyword Ad APIs occurs. 400