발송 실패 리포트 확인과 대응 방법

🧭 접수 성공과 발송 성공은 다릅니다

발송 결과에는 두 단계가 있습니다. 비즈고가 요청을 받았다는 접수 결과, 그리고 메시지가 실제로 단말기에 도착했는지 알려주는 발송 결과입니다. API를 호출했을 때 반환되는 A000은 발송 요청이 정상적으로 접수됐다는 의미입니다. 실제 발송 결과는 이후 전달되는 메시지 리포트의 reportCode로 확인해야 합니다. 리포트를 받고 조회하는 방법은 메시지 발송 결과 확인하는 방법, 조회 방식부터 로그 관리까지에서 다뤘습니다.

리포트에는 메시지 서비스별로 리포트 타입(reportType)이 정의되어 있습니다. 접수 결과와 전송 결과로 나뉘며, 발송 성공과 실패는 전송 결과 리포트로 판단합니다.

이 구조는 채널 공통입니다. 비즈고 API로 발송하는 아래 채널 모두 같은 리포트 규격으로 결과가 돌아옵니다.

• 문자메시지(SMS·LMS·MMS)
• 국제 메시지
• RCS(Rich Communication Services)
• 카카오톡 비즈메시지(알림톡·브랜드 메시지)

채널이나 유형이 늘어도 결과를 확인하고 실패에 대응하는 절차는 하나로 유지됩니다. 그래서 이 글의 대응 기준은 문자부터 카카오톡 비즈메시지까지 그대로 적용되죠.

🔍 실패 원인은 리포트 코드가 알려줍니다

실패 리포트에서 먼저 확인할 필드는 리포트 코드(reportCode)와 상세 내용(reportText)입니다. 코드만 확인해도 어떤 이유로 실패했는지 알 수 있습니다. 그렇다면 코드는 어디서 확인해야 할까요?

1) API 리포트에서 확인하기

웹훅(Webhook)이나 폴링(Polling)으로 수신한 리포트 본문에 리포트 코드가 함께 들어 있습니다. 10000은 단말기에 정상 도착했다는 성공 코드입니다. 실패 코드는 미등록 발신번호부터 단말기 상태까지 원인별로 정의되어 있습니다. 전체 코드 목록은 비즈고 API 개발문서의 코드표에서 확인할 수 있습니다.

2) 콘솔 발송내역에서 확인하기

개발 연동을 거치지 않고도 웹 콘솔에서 단건 실패를 추적할 수 있습니다. [통계/내역 → 시스템 발송 → 발송내역] 메뉴에서 메시지 타입, 발송 상태 등 조건을 조합해 검색합니다. 단건 상세 화면의 Raw Data에서는 API 호출 당시의 원본 요청을 확인할 수 있습니다. 발송 상태 타임라인은 접수부터 결과 수신까지의 단계를 시간순으로 보여줍니다.

🛠 실패 유형별 대응 방법

코드를 확인했다면 다음은 조치입니다. 실패 원인이 발송 설정에 있는지, 수신자 쪽에 있는지에 따라 해야 할 일이 달라집니다. 재발송부터 하기 전에 아래 유형별 대응 방법을 먼저 확인해 보세요.

1) 발송 설정을 바로잡아야 하는 실패

같은 조건으로 재발송하면 같은 코드가 반복되는 유형입니다.

• 미등록 발신번호(33023) : 사전등록되지 않은 발신번호로 발송한 경우
• 발신번호 변작 방지 부가 서비스 가입(33018) : 발신번호가 통신사의 번호도용문자차단 서비스에 가입되어 있는 경우
• 템플릿 불일치(63016) : 발송 내용이 승인된 알림톡 템플릿과 다른 경우

이 유형은 콘솔에서 발신번호와 템플릿 등록 상태를 점검하고 바로잡은 뒤 발송해야 합니다. 그리고 번호도용문자차단은 해당 번호의 통신사에서 부가서비스를 해지해야 발송이 가능해집니다.

2) 수신자 상태로 발생하는 실패

발송 시점에 통제할 수 없는 유형입니다.

• 단말기 전원 꺼짐(32003)·음영지역(32005) : 수신 가능한 상태가 되면 이통사 구간에서 다시 전달을 시도하는 경우
• 카카오톡 사용자 아님(63019)·알림톡 수신 차단(63020) : 카카오톡으로는 도달할 수 없는 수신자
• RCS 미지원 단말(33101) : 단말기가 RCS를 지원하지 않는 경우

이 유형에서 해야 할 일은 재발송보다 대체 발송(Fallback)을 고려하시길 권장합니다. 실패 시 다시 보낼 메시지 타입과 내용을 발송 요청에 미리 지정해 두면 인포뱅크 서버에서 자동으로 대체 발송을 처리합니다. 고객사 서버에서 실패 결과를 받아 다시 요청할 필요가 없죠. 대체 발송은 카카오톡 비즈메시지·RCS 실패 시 문자로 잇는 방향으로 설계합니다. 설정 방식은 개발자센터의 Fallback 메시지(대체발송) 가이드에서 확인할 수 있습니다.

3) 성공으로 기록되는데 고객이 받지 못하는 경우

메시지 유형 중 문자 발송에서 자주 나타나는 상황입니다. 리포트에는 성공으로 남았는데 정작 고객의 메시지함에는 보이지 않습니다. 고객이 가입한 통신사의 스팸 차단 부가서비스가 메시지를 스팸 보관함으로 옮겼기 때문입니다. 단말기까지 전달 자체는 성공했으므로 리포트에도 성공으로 기록됩니다.

이 유형은 코드로 걸러낼 수 없어 사후 안내와 예방이 함께 필요합니다. 고객 문의가 오면 스팸 보관함 확인과 스팸 허용 등록을 안내합니다. 이러한 유형을 예방하기 위해서는, 스팸으로 오인되기 쉬운 과도한 특수문자나 반복 문구 사용을 줄여 주세요. 문자 발송 실패의 다른 원인은 문자 전송이 실패하는 5가지 원인과 해결 방법에서 확인할 수 있습니다.

📡 받지 못한 리포트는 어떻게 보완할까?

실패 코드만큼 자주 마주하는 문제가 리포트 누락입니다. 발송은 됐는데 결과가 돌아오지 않으면 성공과 실패를 판단할 수 없습니다. 비즈고는 리포트를 받는 방식을 웹훅, 폴링, 개별조회 세 가지로 제공합니다. 여기서는 각 방식에서 누락이 생기는 지점과 보완 방법을 중심으로 정리했습니다. 세 방식의 상세 설정은 메시지 발송 결과 확인하는 방법, 조회 방식부터 로그 관리까지와 비즈고 개발자센터 메시지 리포트에서 확인할 수 있습니다.

1) 웹훅으로 실시간 수신받기

웹훅 리포트는 1건당 1회 전달되고, 수신한 쪽에서 규격에 맞는 응답을 돌려줘야 합니다. 타임아웃은 5초, 재시도는 최대 3회입니다. 응답이 정상 처리되지 않으면 해당 리포트는 웹훅으로 받지 못할 수 있습니다. 리포트가 자주 비면 수신 서버의 응답 규격과 처리 시간부터 점검해 보세요.

2) 폴링으로 주기적으로 가져오기

폴링은 수신 서버가 일정 주기로 비즈고에 리포트를 요청해 가져오는 방식입니다. 웹훅으로 받지 못한 리포트도 폴링으로 확인할 수 있습니다. 가져온 리포트는 응답의 reportId로 수신 확인 처리를 합니다.

3) 개별조회로 누락 건 메우기

개별조회는 특정 건의 리포트를 직접 조회하는 방식입니다. 발송 시 받은 메시지 키(msgKey)로 조회하며, 최대 30일 이전까지 확인할 수 있습니다. 웹훅과 폴링으로도 확인되지 않은 누락 건을 메울 때 씁니다.

다만 API 기반 자동화 조회가 필요하거나, 더 긴 기간의 이력을 관리해야 할 때는 자체 데이터베이스(DB) 저장을 권장합니다. 웹훅이나 폴링으로 수신한 리포트를 그대로 적재하면 보관 기간 제한 없이 발송 이력을 관리할 수 있습니다. 조회 수단별 보관 기간은 앞에서 소개한 발송 결과 확인 글에서 정리했습니다.

💬 자주 묻는 질문

Q1. 발송 성공(A000) 응답인데 메시지가 수신되지 않았다면?

A000은 비즈고 API가 요청을 정상 접수했다는 응답이고, 단말기 수신을 보장하지 않습니다. 실제 수신 여부는 메시지 리포트의 결과 코드로 확인합니다.

Q2. 발송 한도 초과(A320) 응답을 받았다면?

API Key(통합키)를 생성하면 기본 발송 한도가 월 50,000건, 일 5,000건으로 설정됩니다. 발송량이 이를 넘어선다면 이용문의로 한도 상향을 요청해 주시면 됩니다.

Q3. 알림톡 실패 시 문자 대체 발송이 되지 않는다면?

대체 발송 설정 방식은 개발자센터의 Fallback 메시지(대체발송) 가이드에서 먼저 확인하세요. 대체 발송으로 전환된 SMS·LMS에도 각각 메시지 리포트가 전달됩니다. 최종 발송 여부는 전환된 메시지의 리포트 결과 코드로 확인할 수 있어요.

그 밖의 항목은 비즈고 개발자센터의 자주 묻는 질문에서 확인할 수 있습니다.