사이드 메뉴
커뮤니케이션
API 제공
어드민 API
카카오톡 오픈채팅
에러 코드
이 문서는 카카오톡 오픈채팅 API 사용 중 발생할 수 있는 주요 에러와 해결 방법을 안내합니다. 이 외에 에러 코드는 공통 에러 코드를 참고합니다.
도메인이 kapi.kakao.com인 카카오톡 오픈채팅 API를 호출할 때 발생하는 대표 에러 목록입니다. (참고: 응답 코드)
| 에러 코드 | 상태 코드 | 원인 및 에러 메시지 | 해결 방법 |
|---|---|---|---|
-2 | 400 | 올바르지 않은 대상을 지정한 경우 에러 메시지:
| 요청 파라미터 값과 앱 페이즈(Phase)에 맞는 URL인지 확인 후 재요청합니다. |
-2 | 400 | 올바르지 않은 도메인 ID를 사용한 경우 에러 메시지: domainId이 유효하지 않습니다. | 해당 앱 ID로 발급받은 domain_id인지 확인하고, 앱 페이즈에 맞는 환경으로 재요청합니다. |
-2 | 400 | 파라미터 값 제한(nickname, link_name, link_description 등)을 위반한 경우에러 메시지:
| 문자열 길이, 허용 문자, 금칙어 포함 여부를 확인해 수정 후 재요청합니다. |
-5 | 403 | 앱에 카카오톡 오픈채팅 API 사용 권한이 없는 경우 에러 메시지: permission denied | 이용 정책을 참고해 사용 권한을 신청합니다. |
-2 | 400 | 오픈채팅 생성 시 타입 설정 권한이 없는 경우 에러 메시지: Unsupprted Link Type. | 이용 정책을 참고해 타입 설정 권한을 신청합니다. |
-3 | 403 | 앱에서 카카오톡 오픈채팅 기능이 비활성화된 경우 에러 메시지: App(OpenChatAPITest) disabled TALK_OPENCHAT service. | 이용 정책을 참고해 권한을 신청하거나 기능을 활성화합니다. |
-3 | 403 | 동의항목이 설정되지 않은 경우 에러 메시지: [OpenChatAPITest] App disabled [talk_openchats] scopes for [OPENCHAT_CREATE] API on developers.kakao.com. Enable it first. | 필요한 동의항목을 참고해 [카카오톡 오픈채팅 참여 및 관리] 동의항목을 설정합니다. |
-101 | 400 | 앱과 연결(가입)되지 않은 사용자로 요청한 경우 에러 메시지: NotRegisteredUserException | 사용자와 앱을 연결한 뒤 다시 요청합니다. |
-402 | 403 | 사용자가 필수 동의항목에 동의하지 않은 경우 에러 메시지:
| 동의항목 추가 동의 요청으로 필요한 동의를 받은 뒤 재요청합니다. |
-2 | 400 | 이미 퇴장한 멤버에게 퇴장을 요청한 경우 에러 메시지: chat(or link) not found | 이미 채팅방에서 퇴장한 사용자이므로 예외 처리합니다. |
-2 | 400 | 멤버가 아닌 사용자의 멤버 프로필 변경을 요청한 경우 에러 메시지: 채팅방이 없습니다. | 멤버가 아닌 사용자는 멤버 프로필 변경을 할 수 없으므로 예외 처리합니다. |
-4 | 403 | 멤버가 아닌 사용자를 대상으로 방장 변경/부방장 지정 또는 해제를 요청한 경우 에러 메시지: blocked action | 멤버인 사용자만 대상으로 방장 변경, 부방장 설정을 요청합니다. |
-4 | 403 | 사용자 제재 상태로 API를 호출한 경우 에러 메시지: user is blocked | 해당 사용자는 제재되어서 해당 API를 수행할 수 없습니다. |
-2 | 400 | 방장이 채팅방 입장을 요청한 경우 에러 메시지: check out param restriction(characters, length, banded words) | 방장은 채팅방 입장이 불가하므로 해당 오픈채팅의 방장 정보를 참고해 예외 처리합니다. |
-4 | 403 | 방장이 채팅방 퇴장을 요청한 경우 에러 메시지: 채팅방을 나갈 수 없습니다.\n방장이 채팅방을 나가려면 방장을 다른 대화상대로 변경하거나 채팅방도 함께 삭제해야 합니다. | 방장인 사용자는 채팅방 퇴장으로 나갈 수 없으므로, 방장인지 여부를 확인하고 채팅방 퇴장 요청을 할 수 없도록 하거나 응답을 확인해 예외 처리합니다. 주의 사항을 확인합니다. |
-4 | 403 | 방장이 아닌 멤버가 오픈채팅 변경/삭제를 요청한 경우 에러 메시지: blocked action | 픈채팅은 방장만 채팅방 정보 변경, 채팅방 삭제할 수 있으므로, 방장이 아닌 멤버가 채팅방 정보 변경 또는 채팅방 삭제를 요청할 수 없도록 하거나 에러 응답에 대해 예외 처리합니다. |
-2 | 400 | 현재 방장을 대상으로 방장 변경을 요청한 경우 에러 메시지: given target id equals current host id | 새로운 방장 대상 사용자 ID로 방장 변경을 재요청합니다. |
-4 | 403 | 방장이 아닌 사용자가 방장 변경을 요청한 경우 에러 메시지: blocked action | 방장 사용자의 액세스 토큰 또는 ID로 방장 변경을 요청합니다. |
-2 | 400 | 이미 부방장인 사용자를 다시 부방장으로 지정한 경우 에러 메시지: INVALID_ARGUMENT | 이미 부방장인 사용자는 다시 부방장으로 지정할 수 없습니다. |
-2 | 400 | 부방장이 아닌 사용자를 부방장 해제한 경우 에러 메시지: INVALID_ARGUMENT | 부방장이 아닌 사용자는 부방장에서 해제할 수 없습니다. |
-4 | 403 | 방장이 아닌 사용자가 부방장 지정 또는 해제를 요청한 경우 에러 메시지: blocked action | 방장 사용자의 액세스 토큰 또는 ID로 부방장 설정을 요청합니다. |
- | 400 | 여러 사용자 부방장 지정 또는 해제 시 일부 대상이 유효하지 않은 경우 에러 메시지: target_id contains invalid id(s) | 대상 중 일부 사용자를 부방장 지정 또는 해제할 수 없는 경우, 모든 대상에 대해 실패 처리하고 에러를 반환합니다. 에러 코드와 메시지는 부방장 지정에 실패한 원인 중 한 가지만 포함합니다. 각 사용자를 개별적으로 부방장 설정을 요청합니다. |
-10 | 400 | 부방장 지정 가능 인원(최대 5명)을 초과한 경우 에러 메시지: exceed the service meta limit | 부방장은 최대 5명까지만 지정 가능합니다. 부방장 설정을 참고합니다. |
-2 | 400 | 링크/프로필 이미지 업로드 또는 스크랩에 실패한 경우 에러 메시지: failed to upload the image. | 이미지 URL이 3초 안에 응답하는 정상 상태인지 확인합니다. 이미지 용량 제한을 참고합니다. |
-2 | 400 | 스크랩 요청 도메인이 등록되지 않은 경우 에러 메시지: only allowed registered site domains on developers.kakao.com | request_url 도메인이 앱 관리 페이지의 [앱] > [제품 링크 관리] > [웹 도메인]에 등록되어 있는지 확인합니다. |
-2 | 400 | 해당 앱에 등록되지 않은 메시지 템플릿 ID를 사용한 경우 에러 메시지: Template 123456 not found | [도구] > [메시지 템플릿]에서 해당 앱의 템플릿을 등록하거나 올바른 템플릿 ID로 요청합니다. |
-401 | 401 | 액세스 토큰이 만료되었거나 유효하지 않은 경우 에러 메시지: this access token does not exist | 토큰을 갱신 또는 재발급한 뒤 재요청합니다. |
-10 | 400 | 링크 생성 수 또는 멤버 수 쿼터를 초과한 경우 에러 메시지: exceed the service meta limit | 쿼터 사용량을 확인하고 쿼터를 참고해 재시도합니다. |
-10 | 400 | 방장 변경 가능 횟수(1일 1회)를 초과한 경우 에러 메시지: exceed the service meta limit | 방장 변경은 하루 한 번만 가능합니다. 방장 변경을 참고합니다. |