연동이 실패할 때

## 먼저 확인할 3가지 원인을 찾기 전에 아래를 확인하면 절반은 해결됩니다. 1. **키를 복사할 때 공백·줄바꿈이 섞였는지** — 가장 흔한 원인입니다. 입력창을 비우고 다시 붙여 넣어 보세요 2. **연동에 쓴 플랫폼 계정이 관리자 권한인지** — 일반 계정은 API 키를 못 만들거나 조회 범위가 좁습니다 3. **사업자 인증이 그 플랫폼에서 끝났는지** — 미인증 상태에서는 키가 발급돼도 데이터가 비어 있습니다 ## 오류 메시지별 대응 ### 인증 자체가 실패 | 메시지 / 증상 | 원인 | 대응 | |---|---|---| | `API Key가 유효하지 않습니다` | 키 오입력 또는 폐기·만료 | 플랫폼에서 재발급 후 다시 입력 | | `invalid_client` | Client ID/Secret 오타 | 앞뒤 공백 확인하고 다시 복사 | | `401 Unauthorized` | 키 만료 또는 권한 철회 | 재발급 또는 **계정 연결** 재시도 | | `403 Forbidden` | 키는 유효하지만 권한 범위 부족 | 플랫폼에서 필요한 읽기 권한을 추가 후 재발급 | | 저장은 되는데 연결 테스트가 계속 실패 | 필수 값 중 하나가 다른 값 | Customer ID / Merchant ID / Account ID 를 플랫폼 화면에서 재확인 | ### 계정 연결(OAuth) 실패 | 메시지 / 증상 | 원인 | 대응 | |---|---|---| | `redirect_uri_mismatch` | 플랫폼에 등록된 콜백 주소와 실제 요청이 불일치 | **직접 해결 불가** — 운영 담당자에게 문의 | | `unauthorized_client` | 앱이 아직 심사 통과·라이브 상태가 아님 | 운영 담당자에게 문의 (테스트 사용자 등록 또는 심사 필요) | | `invalid_scope` | 신청되지 않은 권한을 요청 | 운영 담당자에게 문의 | | `access_denied` | 승인 화면에서 취소 또는 거부 | 정상 동작. **계정 연결** 을 다시 눌러 허용 | | 팝업이 아예 안 열림 | 브라우저 팝업 차단 | 주소창 팝업 차단 아이콘에서 이 사이트 허용 | | 팝업이 열렸다 바로 닫힘 | 이미 로그인된 다른 계정으로 처리됨 | 해당 플랫폼에서 로그아웃 후 재시도 | | 연결은 됐는데 특정 데이터만 계속 0 | 승인 화면에서 권한 일부를 해제 | **계정 연결** 을 다시 눌러 **모두 허용** | > `redirect_uri_mismatch` · `unauthorized_client` · `invalid_scope` 는 **서비스 쪽 앱 설정** 문제입니다. > 고객이 설정으로 해결할 수 없으니 [문의](/news/guide/contact)해 주세요. ### 채널별로 자주 나는 문제 | 채널 | 증상 | 원인 · 대응 | |---|---|---| | Google Ads | 키는 저장되는데 데이터 없음 | Developer Token 이 아직 **승인 대기** 상태. 승인 후 다시 시도 | | Google Ads | 특정 계정만 조회 안 됨 | Customer ID 가 MCC(관리 계정)인지 확인. 실제 광고 계정 ID 를 입력 | | Meta Ads | 토큰은 유효한데 지표 0 | Ad Account ID 형식 확인(`act_` 접두). System User 에 **ads_read** 권한 부여 여부 확인 | | Instagram | 계정 연결 후 데이터 없음 | 계정이 **비즈니스/크리에이터**여야 하고 **Facebook 페이지에 연결**돼 있어야 합니다 | | 네이버 블로그 | 방문자 수가 안 나옴 | 정상입니다. 방문자 통계는 공개 API 미지원 — 게시물 조회만 가능 | | Cafe24 | 연결 후 주문이 안 보임 | 앱 권한에 **주문 조회** 가 포함됐는지 확인 후 재연결 | | Toss Place | `401` · Merchant 불일치 | POS 로그인 ID 를 Merchant ID 로 잘못 넣은 경우가 많습니다. 가맹점 식별자를 확인 | | Jira | 인증 실패 | Base URL 형식 `https://<조직>.atlassian.net` · 로그인 이메일 · API Token 3개가 모두 맞아야 합니다 | | 이메일(IMAP) | 로그인 실패 | 2단계 인증 계정은 **앱 비밀번호**를 발급해 넣어야 합니다. 일반 비밀번호로는 실패 | | 이메일(IMAP) | 서버 주소 오류 | 직접 입력 모드에서 호스트·포트·SSL 설정 확인 (IMAP 보통 993) | | 법인 계좌 | 인증서 오류 | 인증서 파일(.cer/.der)과 개인키(.key)가 **한 쌍**인지, 비밀번호가 맞는지 확인 | | 법인 계좌 | 갑자기 중단 | **공동인증서 만료** 여부 확인 (보통 1년) | | 법인카드 | 로그인 실패 | 카드사 홈페이지 비밀번호 변경 또는 **계정 잠김**. 홈페이지에서 먼저 해제 | ## 순서대로 진단하기 위 표에서 답을 못 찾았다면 아래 순서로 좁혀 보세요. 1. **다른 채널은 정상인가?** - 다른 채널도 전부 실패 → 계정 권한 또는 서비스 문제 - 이 채널만 실패 → 이 채널의 자격증명·권한 문제 2. **플랫폼 콘솔에서 직접 데이터가 보이는가?** - 콘솔에도 데이터가 없다 → 플랫폼 쪽 문제(집계 지연·계정 확인) - 콘솔에는 있는데 모닝인사이트에만 없다 → 권한 범위 또는 조회 대상 ID 문제 3. **연결 테스트는 통과하는가?** - 통과 안 함 → 자격증명 문제 (재발급) - 통과하는데 데이터 없음 → 권한 범위 또는 집계 지연 → [데이터가 보이지 않을 때](/news/guide/trouble-data) 4. **최근에 무엇이 바뀌었나?** - 플랫폼 비밀번호 변경 · 2단계 인증 적용 · 담당자 퇴사 · 인증서 갱신 - 하나라도 있으면 → [연동 상태 · 재인증](/news/guide/integration-refresh) ## 문의할 때 함께 알려주실 것 빠른 확인을 위해 아래를 함께 보내주세요. **키나 비밀번호는 절대 포함하지 마세요.** - 어떤 채널인지 - 어느 단계에서 막혔는지 (저장 / 연결 테스트 / 계정 연결 / 데이터 표시) - 화면에 나온 오류 메시지 원문 (스크린샷) - 시도한 시각 - 최근에 바뀐 것이 있는지 [문의하기](/news/guide/contact) ## 관련 문서 - [데이터가 보이지 않을 때](/news/guide/trouble-data) — 연동은 됐는데 숫자가 안 나올 때 - [연동 상태 · 재인증 · 토큰 만료](/news/guide/integration-refresh) - [플랫폼별 사전 준비물](/news/guide/integration-checklist) - [문의하기](/news/guide/contact)