페이지 이동경로
  • 문서>
  • 카카오톡 공유>
  • 문제 해결

카카오톡 공유

문제 해결

이 문서는 카카오톡 공유 이용 중 발생할 수 있는 주요 에러와 해결 방법을 안내합니다.

에러 코드별 문제 해결

카카오톡 공유 API 사용 시 발생할 수 있는 에러 코드별 해결 방법을 안내합니다.

에러 코드 상태 코드 원인 해결 방법
4002 400 잘못된 요청을 보낸 경우 개발 문서를 확인해 올바른 규격에 맞게 API를 호출합니다.
상황별 문제 해결 참고
4003 400 잘못된 앱 키를 사용했거나 일시적 오류가 발생한 경우 API 호출에 사용한 앱 키가 올바른지 확인하거나, 잠시 후 다시 시도합니다.
4005 400 지원하지 않는 브라우저를 사용한 경우 다른 브라우저나 Internet Explorer는 11 이상 버전으로 다시 시도합니다.
4006 400 기본으로 제공되는 카카오톡 공유 쿼터를 초과한 경우 쿼터 상향을 신청합니다. 심사 승인 후, 다시 시도합니다.
4007 400 일시적으로 사용량을 초과한 경우 잠시 후 다시 시도합니다.
4008 400 카카오톡 이용이 제재된 사용자라 카카오톡 공유를 이용할 수 없는 경우 카카오 고객센터로 문의주시기 바랍니다.
4009 400 [관리자만 말하기] 옵션이 활성화되어 있는 오픈채팅방에서 관리자가 아닌 사람이 공유한 경우 [관리자만 말하기] 옵션을 비활성화한 후 다시 시도합니다.
4011 401 잘못된 요청으로 인증에 실패한 경우 요청 시 사용한 앱 키를 확인합니다.
데브톡으로 문의합니다.
4012 401 카카오계정과 카카오톡이 연결되어 있지 않은 경우 카카오톡의 [더보기] > [설정] > [카카오계정]에서 로그인 후 다시 시도해 주세요.
4013 401 카카오계정이 제재된 경우 카카오 고객센터로 문의합니다.
4015 401 사용자 등록에 실패한 경우 잠시 후 다시 시도합니다.
4016 401 허가되지 않은 요청인 경우 -
4017 401 카카오 계정 인증에 실패한 경우 잠시 후 다시 시도합니다.
4018 401 공유를 완료하기 전 다른 카카오계정으로 로그인된 경우 현재 로그인된 카카오계정을 확인한 후 다시 시도해 주세요.
4019 401 잘못된 요청으로 인증에 실패한 경우 상황별 문제 해결을 참고합니다.
4020 401 카카오디벨로퍼스 앱 또는 개발자 계정이 제재된 경우 데브톡으로 문의합니다.
4041 404 카카오톡으로 공유한 URL이 유효하지 않은 경우 카카오톡 공유 API 호출 시, 올바른 URL을 전달합니다.
5001 500 서버 내부 오류가 발생한 경우 잠시 후 다시 시도하거나, 상황별 문제 해결를 참고합니다.
5005 500 서버 내부 오류가 발생한 경우 잠시 후 다시 시도합니다.

상황별 문제 해결

문제가 발생하는 원인은 상황에 따라 다양합니다. 아래 방법으로도 문제가 해결되지 않으면 데브톡으로 문의합니다.

4002 에러

원인
  • 공유한 URL의 도메인이 앱의 Web 플랫폼에 등록되지 않은 경우
  • 요청한 메시지 템플릿의 규격이 맞지 않는 경우
  • 카카오톡 공유 시 사용한 메시지 템플릿 ID가 유효하지 않은 경우
  • SDK 버전이 낮아 카카오톡 공유 기능이 지원되지 않는 경우
해결 방법
  1. 공유한 URL의 도메인이 카카오디벨로퍼스 앱의 Web 플랫폼에 등록되어 있는지 확인합니다. (참고 플랫폼)
  2. 메시지 템플릿을 사용할 때, 올바른 규격에 맞게 API를 호출합니다. (참고: 개발 문서)
  3. 앱에 등록한 메시지 템플릿의 ID가 맞는지 확인한 후, 다시 요청합니다. (참고: 사용자 정의 템플릿)
  4. 최신 버전의 SDK를 사용하도록 수정합니다.

4019 에러

invalid android_key_hash or ios_bundle_id or web_site_url

{"error":"misconfigured","error_description":"invalid android_key_hash or ios_bundle_id or web_site_url","error_code":"KOE009"}
원인
  • 앱에서 전달한 키 해시가 등록된 키 해시와 다른 경우
  • 앱에 등록된 번들 ID가 실제 서비스와 다른 경우
  • 앱에 등록한 도메인과 요청에서 전달된 도메인이 다른 경우
해결 방법
  1. Web, Android, iOS 플랫폼 정보가 실제 서비스와 일치하는지 확인합니다. (참고: 플랫폼)
  2. [앱] > [일반] > [플랫폼] > [Web]에서 등록한 도메인 목록에 요청에서 전달된 도메인(caller 값)이 포함되어 있는지 확인합니다.
  3. 안드로이드의 경우, 앱에서 사용하는 키 해시가 카카오디벨로퍼스에 등록된 키 해시와 일치하는지 확인하고, 필요시 키 해시 등록 방법을 참고하여 추가 등록합니다.
  4. Google Apps Script 웹 앱을 사용하는 경우, Google Apps Script 웹 앱을 사용하는 경우를 참고하해 도메인을 등록합니다.
  5. App Distribution으로 배포한 앱의 경우, App Distribution으로 배포한 앱의 경우를 참고해 실제 배포 앱의 키 해시를 확인 및 등록합니다.
참고 문서

domain mismatched

[-401] domain mismatched! caller=https://xx. check out registered web domains.
원인
  • 앱에 등록한 도메인과 실제 API 요청에서 전달된 도메인이 일치하지 않은 경우
해결 방법
  1. [앱] > [일반] > [플랫폼] > [Web]에서 등록한 도메인 목록에 요청에서 전달된 도메인(caller 값)이 포함되어 있는지 확인합니다.
  2. Google Apps Script 웹 앱을 사용하는 경우, Google Apps Script 웹 앱을 사용하는 경우를 참고해 도메인을 등록합니다.

wrong appKey(null) format

{"name":"KAPIError","msg":"wrong appKey(null) format","code":-401}
원인
  • 도메인을 등록한 앱의 앱 키가 아닌 다른 앱의 앱 키를 사용해 API를 호출한 경우
  • 사용하는 플랫폼에 맞지 않는 앱 키를 사용해 API를 호출한 경우
  • 앱 키 값이 누락되거나 오타가 있는 경우
해결 방법
  1. 카카오디벨로퍼스에서 도메인을 등록한 앱의 앱 키를 사용해 API를 호출했는지 확인합니다.
  2. 사용하려는 플랫폼에 맞는 앱 키를 사용했는지 확인합니다. (참고: 플랫폼별 앱 키)
  3. 앱 키 값 전체가 누락 없이 잘 전달되었는지 확인합니다.

Google Apps Script 웹 앱을 사용하는 경우

  1. Web 플랫폼 정보에 전체 URL이 아닌 기본 도메인만 등록되어 있는지 확인합니다.
    • (O) https://script.google.com
    • (X) https://script.google.com/macros/s/AKfycb.../exec
  2. 웹 앱이 iframe 내에서 실행될 경우, iframe이 로드된 실제 도메인을 사이트 도메인으로 등록했는지 확인합니다. GAS 웹 앱의 경우 https://script.google.com/macros/... 패턴의 URL로 제공되지만, 실제 콘텐츠는 iframe으로 로드되므로 도메인 정보가 iframe이 로드한 도메인과 다를 수 있습니다.
  3. URL 단축 서비스(예: bit.ly)를 사용하는 경우, 최종 리다이렉트되는 도메인을 사이트 도메인으로 등록합니다. 단축 URL의 경우, 유효한 사이트 도메인으로 인식되지 않을 수 있습니다.

App Distribution으로 배포한 앱인 경우

  1. 배포한 앱에서 어떤 키 해시를 사용하는 지 확인하기 위해 앱 내에서 키 해시를 출력해 로깅합니다.
    • Android: Log.d("KakaoSDK", message)
    • iOS: print("KakaoSDK: (message)")
    • JavaScript: console.log("KakaoSDK:", message)
    • Flutter: print(await KakaoSdk.origin)
  2. 로깅된 키 해시와 카카오디벨로퍼스에 등록된 키 해시를 비교합니다. 만약 두 키해시가 일치하지 않는다면, 카카오디벨로퍼스에서 확인한 키 해시를 앱에 추가로 등록합니다.
  3. 그래도 해결되지 않는다면, 앱 서명 키 인증서가 변경될 수 있으므로 구글 플레이 콘솔에서 앱 서명 키 인증서의 SHA-1 지문을 다시 확인하고 키 해시를 재생성합니다. 재생성한 키 해시는 카카오디벨로퍼스에 추가로 등록해야 합니다.

5001 에러

원인
  • 파라미터 구성이 잘못된 경우
  • 파라미터로 전달한 이미지 URL이 외부에서 접근 불가(예: 사내망, 방화벽 등)하여 카카오 이미지 스크랩 서버가 접근에 실패한 경우
  • 브라우저에서 쿠키 사용이 제한된 경우 (참고: 쿠키 제한 환경에서 발생하는 오류)
  • 브라우저에서 크롬 확장 프로그램(Extension) 등 외부 요소에 의해 쿠키가 정상적으로 동작하지 않은 경우
해결 방법
  • 카카오톡 공유에 사용된 이미지가 유효한지 확인합니다.
  • 카카오톡 공유에 사용된 이미지가 외부에서 접근 가능한지 확인합니다.
    • 서비스 서버에서 방화벽을 사용하는 경우, 카카오 스크랩 서버의 접근을 차단해 이미지가 표시되지 않을 수 있습니다. 방화벽을 참고해 ACL(Access Control List, 접근 제어 목록)에 카카오 스크랩 서버의 IP를 등록합니다.
  • 브라우저의 쿠키 사용 설정이 꺼져 있지 않은지 확인합니다.
  • 시크릿(시크릿/인프라이빗) 모드에서 카카오톡 공유 기능을 다시 시도해 봅니다. 정상 동작하는 경우, 크롬 등 브라우저에 설치된 확장 프로그램 중 쿠키나 브라우저 동작에 영향을 줄 수 있는 확장 프로그램을 비활성화한 후 다시 시도합니다.
참고: 쿠키 제한 환경에서 발생하는 오류

카카오 로그인과 카카오톡 공유 기능은 Cross-Site Request Forgery(CSRF) 공격을 막기 위해 CSRF 토큰을 검증합니다.

쿠키가 정상적으로 동작하지 않는 환경에서는 정상적인 API 요청도 실패할 수 있습니다. 쿠키 사용이 제한된 브라우저는 서버로 세션 ID를 보내지 못해 서버는 사용자의 세션을 찾지 못하고, 유효한 CSRF 토큰을 확인할 수 없게 됩니다. 결과적으로 요청은 유효하지 않은 토큰으로 간주되어 에러가 발생합니다.

데브톡 문의

이 문서에서 해결 방법을 찾지 못한 경우, 아래 정보와 함께 데브톡으로 문의합니다.

  • [필수] 앱 ID
  • [필수] UUID (에러 화면 캡쳐본이 아닌 UUID 값을 복사해서 전달)
  • 상세 에러 메시지
  • SDK를 사용하는 경우, SDK 버전
카카오톡 공유> 문제 해결