오류 코드

모든 오류는 HTTP 상태 코드와 함께 아래 형식의 JSON 으로 반환됩니다. 코드 값(error.code)은 변경되지 않으므로 프로그램에서는 code 로 분기하세요. message 는 사람이 읽는 설명이며 바뀔 수 있습니다.

JSON

{
  "request_id": "req_a2b3c74d17246af7aa5f",
  "error": {
    "code": "MESSAGE_TOO_LONG",
    "message": "SMS 본문은 90 bytes 이하이어야 합니다.",
    "details": {
      "channel": "sms",
      "hint": "90 bytes 를 넘으면 /v1/messages/lms 를 사용하세요."
    }
  }
}

입력값 오류에는 details.field 에 문제가 된 필드명이 들어 있습니다. 문의 시 request_id 를 알려 주세요.

재시도 기준

HTTP	의미	재시도
2xx	성공 / 접수	—
400 · 401 · 403 · 404 · 405 · 413 · 415 · 422	요청 자체를 고쳐야 하는 오류	하지 않음
402	잔액 부족	충전 후
409	처리 중 / 취소 불가	`REQUEST_IN_PROGRESS` 만 `Retry-After` 후
429	요청 제한	`Retry-After` 후 (같은 Idempotency-Key)
500 · 503	서버 오류 / 일시 장애	지수 백오프로 (같은 Idempotency-Key)

오류 코드 목록

인증 · 계정

HTTP	code	설명
401	`UNAUTHORIZED`	API 키 누락·오류·폐기·만료
403	`IP_NOT_ALLOWED`	키의 허용 IP 목록에 없는 주소
403	`IP_WHITELIST_REQUIRED`	키에 허용 IP 가 등록되지 않음 (관리자 등록 필요)
403	`ACCOUNT_SUSPENDED`	이용이 제한된 계정
403	`API_DISABLED`	계정의 API 사용이 허용되지 않음
503	`API_DISABLED`	외부 API 일시 중단 (점검 등)
403	`BUSINESS_MEMBER_REQUIRED`	알림톡/브랜드메시지는 사업자 회원 전용

요청 형식

HTTP	code	설명
400	`INVALID_JSON`	JSON 파싱 실패 / 본문 없음 / 최상위가 객체가 아님
404	`NOT_FOUND`	존재하지 않는 경로
405	`METHOD_NOT_ALLOWED`	허용되지 않는 HTTP 메서드
413	`PAYLOAD_TOO_LARGE`	JSON 본문 2MB 초과
415	`UNSUPPORTED_MEDIA_TYPE`	Content-Type 이 `application/json` 이 아님
422	`INVALID_REQUEST`	필드 누락·형식 오류·수신자 없음 (`details.field`)
422	`TOO_MANY_RECIPIENTS`	수신자 수 초과 (동일 문구·SMS/알림톡 개별 1,000명, LMS/MMS 개별 문구 500명). `details.max` 참고
422	`INVALID_SEND_AT`	예약 시각 형식 오류 / 과거 / 180일 초과

발송

HTTP	code	설명
402	`INSUFFICIENT_BALANCE`	잔액 부족
403	`SENDER_API_NOT_ENABLED`	해당 발신번호의 API 사용이 허용되지 않음
422	`SENDER_NOT_APPROVED`	미승인·미등록 발신번호
422	`SENDER_BLOCKED`	통신사(KTOA)에서 중지된 발신번호
503	`KTOA_UNAVAILABLE`	발신번호 검증 서비스 일시 장애 (`Retry-After`)
422	`MESSAGE_TOO_LONG`	채널 길이 한도 초과
422	`SPAM_WORD_BLOCKED`	금칙어 포함 (`details.words`)
422	`ALL_RECIPIENTS_REJECTED`	접수 가능한 수신자가 없음 (전원 수신거부 등)
422	`FILE_NOT_FOUND`	MMS 이미지가 없거나 만료됨
422	`INVALID_FILE`	업로드 파일 형식·크기 오류
422	`PROFILE_NOT_FOUND`	발신프로필 없음/비활성
422	`PROFILE_NOT_USABLE`	발신프로필이 차단·휴면 상태
422	`BRAND_NOT_ENABLED`	브랜드메시지 사용 불가 프로필
422	`TEMPLATE_NOT_FOUND`	템플릿 없음 또는 승인·정상 상태 아님
422	`TEMPLATE_VARIABLE_MISSING`	필수 변수 누락 (`details.variable`)
422	`REQUEST_REJECTED`	그 외 업무 규칙 위반 (`message` 참고)

멱등성 · 제한

HTTP	code	설명
409	`REQUEST_IN_PROGRESS`	같은 Idempotency-Key 요청을 처리 중
422	`IDEMPOTENCY_KEY_REUSED`	같은 키를 다른 본문으로 사용
429	`RATE_LIMITED`	초당/분당 요청 한도 또는 인증 실패 과다
429	`CONCURRENCY_LIMIT`	동시 처리 중인 발송 요청이 너무 많음

조회 · 취소

HTTP	code	설명
404	`MESSAGE_NOT_FOUND`	발송 건이 없거나, 내 계정의 건이 아니거나, API 로 접수한 건이 아님 (웹사이트에서 발송한 건 포함)
404	`PROFILE_NOT_FOUND`	템플릿 조회 시 발신프로필 없음
409	`CANCEL_NOT_ALLOWED`	취소 가능한 예약 건이 없음 (이미 발송 시작/취소됨)
422	`CANCEL_NOT_ALLOWED`	브랜드메시지는 취소 불가

서버

HTTP	code	설명
503	`TEMPORARILY_UNAVAILABLE`	일시적 처리 불가 — 같은 요청을 그대로 재시도
503	`PROVIDER_CONFIG_ERROR` · `PRICE_NOT_FOUND`	서비스 설정 문제 — 고객센터 문의
500	`INTERNAL_ERROR`	서버 오류 — `request_id` 와 함께 문의

이 목록에 없는 새로운 code 가 추가될 수 있습니다. 알 수 없는 코드는 HTTP 상태 코드 기준으로 처리하세요. (4xx: 재시도 금지, 5xx: 재시도)