Kakao API
raw JSON → 2025-latest verified Tue May 12 auth: no python install: stale quickstart: stale
Kakao REST API provides access to Kakao Login, KakaoTalk messaging, friends list, maps, and AI features. Primary documentation is in Korean. English docs exist but are incomplete and lag behind Korean versions. No official Python/Node package — all integrations use REST API directly with app keys.
pip install requests Common errors
error {"error":"redirect_uri_mismatch"} ↓
cause The `redirect_uri` parameter sent in the API request does not exactly match one of the Redirect URIs registered in your Kakao Developers application settings (App > Platform Key > REST API Key or JavaScript Key).
fix
Go to Kakao Developers, navigate to your app's 'Platform Key' settings, and ensure the
redirect_uri used in your API request is precisely registered, including scheme (http/https), domain, path, and port. error {"error":"invalid_grant"} ↓
cause This error occurs when the authorization code is expired, has already been used, or is invalid, or if the refresh token used to get a new access token is expired or missing.
fix
Ensure you are using a fresh authorization code for each token request. If refreshing tokens, obtain new tokens through the full Kakao Login process if the refresh token has expired or is invalid.
error {"error":"invalid_client"} ↓
cause The `client_id` (REST API Key) provided in the request is incorrect, has a typo, or the `client_secret` is missing or incorrect when the Client secret feature is activated for your app.
fix
Verify that the
REST API Key used in your request matches the one in your Kakao Developers app settings (App > Platform Key). If 'Client secret' is enabled, ensure it's correctly included in your token issuance requests. error {"msg":"this access token does not exist","code":-401} ↓
cause The access token provided in the request header is invalid, expired, or does not exist. It can also occur if the IP address making the request is not registered in your Kakao Developers app's allowed IP addresses.
fix
Reissue a new access token through the Kakao Login flow. Also, check your Kakao Developers app's 'Advanced Settings' for 'Allowed IP Addresses' and register the server IP making the API calls if applicable.
error {"code":-2,"msg":"invalid parameters"} ↓
cause The API request contains missing required parameters, parameters with incorrect data types, or values outside the acceptable range.
fix
Carefully review the Kakao API documentation for the specific endpoint you are calling. Ensure all required parameters are present, their types are correct, and their values conform to the specified ranges or formats.
Warnings
breaking Client secret is now enabled by default for all new REST API keys. Omitting client_secret in token requests causes KOE101 error. ↓
fix Include client_secret parameter in all Get token API calls, or disable Client secret in app settings
breaking Access tokens expire in 6 hours. Refresh tokens expire in 60 days (extendable to 2 months). Expired access token returns error code -401. ↓
fix Implement token refresh using refresh_token before expiry. Check error code -401 and refresh proactively.
gotcha Error codes are negative integers with no consistent pattern. code:-401 can mean token expired, token not found, or app key deactivated — check msg field for the actual cause. ↓
fix Always read the msg field in error responses, not just the code
gotcha Primary documentation is in Korean at developers.kakao.com. English docs exist but are incomplete and often lag Korean versions by weeks. ↓
fix For complete specs use Korean docs at developers.kakao.com/docs/latest/ko/ — use translation tools if needed
gotcha Token issuance rate limit returns KOE237 error. Not documented clearly in English docs. ↓
fix Implement exponential backoff on KOE237. Check Korean troubleshooting docs for current limits.
gotcha Scope/consent items must be pre-configured in Kakao Developers app settings before requesting. Missing scope returns -402 insufficient scopes error. ↓
fix Configure all required consent items in app settings at developers.kakao.com before going to production
gotcha Admin key has full permissions and must never be exposed client-side. Reissuing app keys is irreversible — all existing keys stop working immediately. ↓
fix Use Admin key only in server-side code. Store in environment variables only.
breaking The ACCESS_TOKEN variable must be defined and populated (e.g., from an environment variable, configuration file, or a successful token retrieval API call) before being used in API requests. ↓
fix Ensure ACCESS_TOKEN is properly defined and assigned a valid value (such as by loading it from an environment variable or obtaining it via an authentication flow) before it is referenced in API calls.
gotcha A NameError: name 'ACCESS_TOKEN' is not defined indicates that the variable was used without being assigned a value. Ensure all variables are defined before use. ↓
fix Define or assign a value to 'ACCESS_TOKEN' before it is used, for example, by loading it from an environment variable, a configuration file, or directly assigning it in the script.
Install
npm install axios Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - - -
3.10 slim (glibc) - - - -
3.11 alpine (musl) - - - -
3.11 slim (glibc) - - - -
3.12 alpine (musl) - - - -
3.12 slim (glibc) - - - -
3.13 alpine (musl) - - - -
3.13 slim (glibc) - - - -
3.9 alpine (musl) - - - -
3.9 slim (glibc) - - - -
Imports
- Authorization header wrong
Authorization: Bearer {REST_API_KEY}correctAuthorization: KakaoAK {REST_API_KEY} - User token auth
Authorization: Bearer {ACCESS_TOKEN}
Quickstart stale last tested: 2026-05-12
import requests
# Get user info with access token
headers = {
'Authorization': f'Bearer {ACCESS_TOKEN}'
}
response = requests.get(
'https://kapi.kakao.com/v2/user/me',
headers=headers
)
print(response.json())