이 문서는 카카오디벨로퍼스에서 제공하는 REST API의 규격 정보를 안내합니다.

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

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

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

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

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

HTTP/1.1 403 Forbidden
{
  "msg": "This api is not allowed by using app_key(${APP_KEY}).",
  "code": -3
}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error=invalid_token
{
  "code":-401,
  "msg":"InvalidTokenException"
}

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"

"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 mismatched! callerIp=xxxxxxxx. check out registered ips."

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

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

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

에러 코드를 참고합니다.

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

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

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