bizgo Developers

응답 코드 해석

비즈고 API는 세 가지 레이어에서 코드를 반환합니다.
각 코드의 위치와 의미를 이해하면 에러를 정확하게 진단하고 처리할 수 있습니다.

응답 구조 개요

{
  "common": {
    "authCode": "A000",
    "authResult": "Success"
  },
  "data": {
    "code": "0000",
    "message": "success",
    "data": {
      "destinations": [
        {
          "to": "01000000000",
          "msgKey": "MSG-20260403-001",
          "reportCode": "1000",
          "reportResult": "success"
        }
      ]
    }
  }
}
위치설명
common.authCode인증 레이어 결과 (API 키 유효성, 권한)
data.code요청 처리 레이어 결과 (발송 요청 수신 여부)
data.data.destinations[].reportCode실제 발송 결과 (이통사·채널 처리 결과)

authCode — 인증 레이어

API 요청 자체의 인증 성공 여부를 나타냅니다. A000이 아니면 요청이 처리되지 않은 것입니다.

authCode의미권장 처리
A000인증 성공정상 처리
A010API 키 없음Authorization 헤더 확인
A020Rate Limit 초과Retry-After 대기 후 재시도
A030API 키 만료 / 비활성콘솔에서 키 상태 확인
A040권한 없음해당 채널 사용 계약 확인
A050IP 차단허용 IP 등록 여부 확인

data.code — 요청 처리 레이어

요청 본문이 올바르게 처리되었는지 나타냅니다.

data.code의미권장 처리
0000요청 정상 수신msgKey 저장 후 리포트 대기
1001destinations 필드 오류수신자 번호·형식 확인
1002messageFlow 필드 오류채널 파라미터 확인
1003필수 파라미터 누락요청 스키마 검토
1010발신번호 미등록콘솔에서 발신번호 등록
1011발신번호 차단이통사 차단 여부 확인
1020알림톡 템플릿 불일치템플릿 코드·변수 확인
1021알림톡 템플릿 미승인카카오 심사 대기 또는 재신청
1030RCS 브랜드 미등록RCS 브랜드 등록 확인
1040잔액 부족충전 후 재시도
9999내부 서버 오류잠시 후 재시도, 지속 시 문의

reportCode — 발송 결과 레이어

실제로 수신자에게 전달된 결과입니다. 채널별로 코드 체계가 다릅니다.

공통 reportCode

reportCode의미권장 처리
1000발송 성공정상 처리
2000수신자 없음 (결번)번호 유효성 검증
2001전원 꺼짐 / 장기 미수신재시도 또는 포기
2002수신 거부수신 거부 목록에 추가
2003번호 이동 실패수신자 번호 업데이트 필요
3000Fallback 발동다음 채널로 자동 전환됨 (정상)
4000채널 일시 장애Fallback 발동 또는 재시도
4001채널 타임아웃Fallback 발동 또는 재시도
9000알 수 없는 오류비즈고 문의

카카오 채널 reportCode

reportCode의미권장 처리
3100카카오 앱 미설치SMS Fallback 확인
3101채널 차단 (수신 거부)Fallback 또는 SMS 발송
3102템플릿 불일치템플릿 내용·변수 검토
3104광고 수신동의 없음수신동의 상태 확인

RCS reportCode

reportCode의미권장 처리
5100RCS 미지원 단말SMS/LMS Fallback 확인
5101RCS 서비스 미가입Fallback 발동 정상
5102메시지베이스 오류messagebaseId 확인

실제 응답 예시

발송 성공

{
  "common": { "authCode": "A000", "authResult": "Success" },
  "data": {
    "code": "0000",
    "message": "success",
    "data": {
      "destinations": [
        {
          "to": "01012345678",
          "msgKey": "MSG-20260403-00123",
          "reportCode": "1000",
          "reportResult": "success"
        }
      ]
    }
  }
}

Fallback 발동 (알림톡 → SMS)

{
  "common": { "authCode": "A000", "authResult": "Success" },
  "data": {
    "code": "0000",
    "data": {
      "destinations": [
        {
          "to": "01012345678",
          "msgKey": "MSG-20260403-00124",
          "reportCode": "3100",
          "reportResult": "fallback",
          "fallback": {
            "channel": "sms",
            "reportCode": "1000",
            "reportResult": "success"
          }
        }
      ]
    }
  }
}

인증 실패 (Rate Limit)

{
  "common": {
    "authCode": "A020",
    "authResult": "Rate limit exceeded"
  }
}

코드 처리 우선순위

요청 시 authCode 확인
  └─ A000 아님 → 인증 오류 처리 (재시도/점검)

data.code 확인
  └─ 0000 아님 → 요청 파라미터 오류 처리

발송 후 reportCode 확인
  └─ 1000 → 성공
  └─ 3000 → Fallback 발동 (다음 채널 reportCode 확인)
  └─ 2xxx → 수신자 문제 (번호 업데이트)
  └─ 4xxx → 채널 장애 (재시도)

다음 단계