커머스 오류

자주 터지는 커머스 오류를 코드별 원인과 대응으로 묶어요.

Commerce API(고객, 상품, 주문, 구독 등) 연동 과정에서 발생하는 에러 코드예요.

v1 API 의 현재 인증 오류와 엔드포인트별 오류는 오류 응답 및 v1 API 레퍼런스를 기준으로 확인해요.

이럴 때 필요해요: Commerce API 호출 시 에러 응답을 받았을 때, 주문·구독·상품 상태 코드를 확인할 때

자주 만나는 에러 TOP 4

연동 중 가장 많이 발생하는 에러와 해결법이에요.

1`ORDER_PRODUCT_STOCK_OUT` · `ORDER_OPTION_STOCK_OUT` 재고 부족

흔한 원인: 동시 주문 시 재고 체크 후 결제 사이에 다른 주문이 먼저 처리됨. 옵션 상품이면 ORDER_OPTION_STOCK_OUT 이에요.

주문서 생성 시점에 재고를 미리 차감(예약)하는 것을 권장해요

2`ORDER_USER_INVALID` 결제 요청 회원정보 불일치

흔한 원인: 프론트엔드에서 보낸 user.id와 서버의 로그인 세션 사용자가 다름.

3`SUBSCRIPTION_WALLET_BLANK` 빌링키 미등록

흔한 원인: 구독 결제 시 빌링키 발급 단계를 건너뜀. 빌링키 삭제 후 구독 결제 시도.

4`INVOICE_PRICE_GT_0` 결제금액 0원

흔한 원인: 할인 적용 후 금액이 0원 이하가 됨. price 파라미터 누락.

에러 응답 형식

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error_code": "ORDER_CANCEL_ALREADY_COMPLETED",
  "message": "이미 결제 취소 처리가 되었습니다"
}json

필드	타입	설명
error_code	String	에러 코드 텍스트 (아래 코드표의 숫자 코드에 대응)
message	String	에러 메시지 (한국어)
payload	Object	추가 데이터 (에러에 따라 포함, 없으면 생략)
pg_error_code	String	PG사 에러 코드 (결제 관련 에러에서만 포함)

아래 코드표의 숫자 코드(예: 3710)는 내부 에러 코드예요. API 응답에서는 이에 대응하는 텍스트(예: "ORDER_CANCEL_ALREADY_COMPLETED")가 error_code 필드로 반환돼요.

커머스 API 인증 에러

api.bootapi.com/v1/** 호출이 인증 단계에서 막힐 때 돌아오는 코드예요. 아래 인증 관련 에러는 결제 SDK 계열 코드라 값이 달라요.

잘못된 Client Key 는 404, 잘못된 Secret Key 는 401 이에요. 401 만 보고 재인증하는 로직은 걸리지 않으니 error_code 로 분기해요.

코드	HTTP	메시지	대처 방법
`PROJECT_SERVER_KEY_INVALID`	404	프로젝트 키를 찾을 수 없습니다	Basic 인증의 clientKey 를 확인해요
`PROJECT_PK_INVALID`	401	비밀 키가 일치하지 않습니다	Basic 인증의 secretKey 를 확인해요
`PROJECT_AT_AUTHORIZE_BASIC_INVALID`	400	Authorization Basic 형식이 잘못되었습니다	`Basic {base64(client_key:secret_key)}` 형식인지 확인해요
`TOKEN_AUTHORIZE_TYPE_INVALID`	400	잘못된 Authorization 타입입니다	`Authorization` 헤더가 없거나 `Basic`·`Bearer` 가 아닐 때예요. 헤더를 확인해요
`PROJECT_CLIENT_KEY_EXPIRED`	401	만료된 Client KEY 입니다	API 연동키에서 새 키를 발급받아요
`PROJECT_FIREWALL_BLOCKED`	401	접근이 허가된 IP가 아닙니다	관리자에서 IP 보안 설정을 확인해요. 차단된 요청 IP 는 응답 `message` 끝에 붙어 와요
`PROJECT_NOT_ALLOW`	401	접근이 불가한 프로젝트입니다	프로젝트 상태를 부트페이에 문의해요
`SELLER_NOT_ALLOW`	401	허가된 판매자 계정이 아닙니다	판매자 계정 상태를 부트페이에 문의해요
`TOKEN_NOT_FOUND`	404	토큰을 찾을 수 없습니다	잘못되었거나 만료된 기존 Bearer 토큰이에요. 신규 연동은 Basic 인증을 사용해요
`API_SCOPE_INVALID`	401	현재 API 키에 필요한 권한이 없습니다	API 연동키에서 scope 를 추가하거나 supervisor 키를 써요

권한 설정과 Bootpay-Role 사용법은 서버 인증에서 다뤄요.

인증 관련 에러

결제 SDK(api.bootpay.co.kr) 계열 코드예요. 커머스 API 는 위 커머스 API 인증 에러를 봐요.

코드	메시지	대처 방법
`AUTHENTICITY_TOKEN_EXPIRE`	인증 정보가 올바르지 않아요	Client Key 또는 Secret Key를 관리자 > 개발자 설정에서 다시 확인해요
`APP_KEY_NOT_FOUND`	Client Key를 찾지 못했어요	관리자 > 개발자 설정 > API 연동키에서 키를 확인해요
`APP_KEY_PLATFORM_NOT_MATCH`	요청한 Platform Type과 SDK Platform Type이 일치하지 않는다	Client Key의 플랫폼 타입(Web/Android/iOS)을 확인해요
`APP_KEY_NOT_REST`	요청한 Client Key가 REST API 키가 아니에요	REST API용 Client Key를 사용해요
`APP_FIREWALL_BLOCKED`	접근이 허가된 IP가 아니에요	관리자 > 개발자 설정 > 보안 정책에서 IP 보안 설정을 확인해요
`APP_SK_NOT_MATCHED`	Secret Key가 올바르지 않아요	관리자 > 개발자 설정에서 Secret Key를 다시 확인해요
`APP_AT_AUTHORIZE_TYPE_INVALID`	Authorization 인증 타입이 올바르지 않아요	`Authorization: Basic {base64}` 형식인지 확인해요
`APP_AT_AUTHORIZE_HEADER_BLANK`	Authorization 헤더가 비어 있어요	`Authorization: Basic {base64(client_key:secret_key)}` 형식으로 헤더를 추가해요
`APP_API_SCOPE_NOT_MATCHED`	현재 사용 중인 API 키에 필요한 권한이 없어요	관리자 > 개발자 설정 > API 연동키에서 API Scope 권한을 추가해요
`ONLY_INTERNAL_SERVER`	부트페이 내부용 API예요. 외부에서는 사용할 수 없어요	외부에서 호출 가능한 API 엔드포인트를 사용해요
`SESSION_RESULT_BLANK`	세션 정보가 비어 있어요	다시 로그인하거나 API 인증 정보를 확인해요
`SERVICE_WALLET_REQUIRED`	서비스 이용료 결제 등록이 필요해요	부트페이 관리자 > 이용요금 > 결제수단 관리에서 지갑을 추가해요
`CURRENCY_DATA_INVALIDATE`	통화/시간 데이터 형식이 잘못됐어요	ISO 8601 표준시 포맷으로 보내준다
`DB_ERROR`	데이터베이스 오류가 발생했어요	잠시 후 재시도하거나 관리자에 문의해요
`REST_API_ERROR`	REST API 처리 중 오류가 발생했어요	요청 파라미터를 확인하고 재시도해요

공통 에러

코드	메시지	대처 방법
`DB_ERROR`	데이터베이스 오류가 발생했어요	잠시 후 재시도하거나 관리자에 문의해요
`EX_UID_DUPLICATED`	이미 존재하는 ex_uid예요	다른 ex_uid를 사용해요
`PROCESS_DUPLICATED`	이미 처리된 요청이에요 (중복 요청)	중복 요청인지 확인해요
`INVALID_PARAMETER`	필수 파라미터를 입력해주세요 (코드 `-48`)	필수 값·허용 값을 확인해요 (`API_PARAM_INVALID` 가 아니라 이 이름으로 와요)
`TIME_INVALID`	시간 포맷이 잘못되었어요 (코드 `-40`)	시각 파라미터를 ISO 8601 형식으로 보내요

에러 코드

Commerce API(고객, 상품, 주문, 구독 등) 연동 과정에서 발생하는 에러예요.

USER_DUPLICATE · USER_GROUP_ALREADY_EXISTS · USER_GROUP_ENROLL_FAILED · USER_GROUP_WITHDRAW_FAILED · PRODUCT_NAME_BLANK · PRODUCT_ID_BLANK · PRODUCT_OPTION_PRICE_INVALID · PRODUCT_OPTION_LENGTH_INVALID · INVENTORY_INSUFFICIENT · INVENTORY_UPDATE_FAILED · INVOICE_NOT_READY · WALLET_TYPE_INVALID · ORDER_SUBSCRIPTION_BILL_CANCELLED_PRICE_OVER · ORDER_SUBSCRIPTION_BILL_CANCELLED_TAX_PRICE_OVER · ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_CANNOT_STATUS · ORDER_SUBSCRIPTION_CANCEL_ALREADY_REQUESTED · ORDER_SUBSCRIPTION_CANCEL_CANNOT_REQUEST_SETTING · ORDER_SUBSCRIPTION_REQUEST_UNABLE · ORDER_SUBSCRIPTION_CANCEL_NOT_FOUND · ORDER_SUBSCRIPTION_CANCEL_NOT_CANCEL_ABLE · ORDER_SUBSCRIPTION_TERMINATE_APPROVE_ERROR · ORDER_SUBSCRIPTION_TERMINATE_CRITICAL_ERROR · SUBSCRIPTION_PAUSE_DURATION_TOO_SHORT · SUBSCRIPTION_TRANSFER_USER_INFO_REQUIRED · ORDER_SUBSCRIPTION_PURCHASE_NOT_ALLOWED · CART_ITEM_SNAPSHOT_CHANGED · WEBHOOK_LOG_NOT_FOUND · WEBHOOK_LOG_URL_BLANK · WEBHOOK_HEADER_CONTENT_TYPE_INVALID · WEBHOOK_RETRY_COUNT_INVALID 는 코드 목록에 이름만 있고 커머스 API 응답으로는 오지 않아요.

고객 관련 에러

코드	메시지	대처 방법
`USER_NAME_BLANK`	고객명은 필수예요	name 파라미터를 입력해요
`USER_PHONE_BLANK`	전화번호는 필수예요	phone 파라미터를 입력해요
`USER_EMAIL_BLANK`	이메일을 입력해요	email 파라미터를 입력해요
`USER_PHONE_OR_EMAIL_BLANK`	전화번호 또는 이메일을 입력해요	phone 또는 email을 입력해요
`USER_ID_EXIST`	이미 사용중인 아이디예요	다른 login_id를 사용해요
`USER_EMAIL_EXIST`	이미 사용중인 이메일이에요	다른 이메일을 사용해요
`USER_ID_BLANK`	로그인 아이디를 입력해요	login_id를 입력해요
`USER_ID_INVALID`	로그인 아이디는 영문+숫자 5~30자예요	형식에 맞는 login_id를 입력해요
`USER_EMAIL_INVALID`	이메일 형식에 맞지 않아요	올바른 이메일 형식으로 입력해요
`USER_LOGIN_FAILED`	가입되지 않은 계정이거나 비밀번호가 틀렸다	login_id와 password를 확인해요
`USER_BLOCKED`	로그인이 제한된 계정이에요	쇼핑몰 관리자에게 문의해요
`USER_LOGIN_PASSWORD_NOT_MATCH`	로그인 비밀번호가 잘못됐어요	password를 확인해요
`USER_JWT_INVALID`	JWT 토큰 정보가 잘못됐어요	다시 로그인하여 유효한 JWT를 발급받아요
`USER_SESSION_INVALID`	세션 정보가 없어요	로그인 세션이 유효한지 확인해요
`USER_ADDRESS_BLANK`	주소를 입력해요	address 파라미터를 입력해요
`USER_PASSWORD_BLANK`	비밀번호를 입력해요	password 파라미터를 입력해요
`USER_NO_LOGIN_ID`	로그인 아이디가 없는 계정이에요	고객에게 login_id를 먼저 등록해요
`USER_EXTERNAL_UID_EXIST`	중복된 회원 UNIQ ID예요	다른 ex_uid를 사용해요
`USER_PASSWORD_INVALID`	유효한 비밀번호가 아니에요	비밀번호 형식 조건을 확인해요
`USER_PASSWORD_FORMAT_INVALID`	비밀번호를 입력하지 않았거나 8자리 이하예요	고객 등록 때 `login_pw` 를 8자 이상으로 넣거나 `extra.skip_password: "true"` 를 보내요
`USER_NOT_FOUND`	회원정보를 찾을 수 없어요	user_id를 확인해요
`USER_NOT_MATCH`	전달한 회원 정보가 서로 달라요	JWT와 `user_id` 또는 `login_id`가 같은 회원을 가리키는지 확인해요
`USER_DELETED`	삭제된 회원이에요	관리자에게 문의해요

고객 그룹 관련 에러

코드	메시지	대처 방법
`USER_GROUP_NOT_FOUND`	회원 그룹 정보를 찾지 못했어요	user_group_id를 확인해요
`USER_COMPANY_NAME_BLANK`	기업회원은 회사명을 입력해야 해요	company_name을 입력해요
`USER_BUSINESS_NUMBER_BLANK`	기업회원은 사업자 등록번호를 입력해야 해요	business_number를 입력해요
`USER_GROUP_EXTERNAL_UID_EXIST`	중복된 사업자 UNIQ ID예요	다른 ex_uid를 사용해요
`USER_GROUP_BUSINESS_NUMBER_ALREADY_EXISTS`	중복된 사업자번호를 가진 그룹이 이미 있어요	기존 그룹을 확인해요
`USER_ALREADY_IN_GROUP`	사용자가 이미 그룹에 속해있어요	그룹 멤버 목록을 확인해요
`USER_NOT_IN_GROUP`	사용자가 그룹에 속해 있지 않아요	사용자의 그룹 소속을 확인해요
`USER_GROUP_NOT_AUTHORIZED`	그룹 정보를 설정할 권한이 없어요	그룹 관리자 권한이 있는지 확인해요
`USER_GROUP_DELETE_UNABLE`	이미 삭제된 그룹이거나 삭제가 불가능한 상태예요	쇼핑몰 관리자에 문의해요
`USER_GROUP_SUBSCRIPTION_PURCHASE_LIMIT_ERROR`	월 구매 한도 금액이 초과했어요	구매 한도를 확인하거나 관리자에게 상향 요청해요
`USER_GROUP_PURCHASE_LIMIT_REQUIRED`	월 구매 한도 금액 값을 입력해요	purchase_limit 값을 입력해요
`USER_GROUP_PURCHASE_LIMIT_BELOW_SUBSCRIBED`	월 구매 한도 금액이 현재 구독 금액보다 적다	현재 구독 금액 이상으로 설정해요
`USER_GROUP_ID_BLANK`	USER_GROUP_ID가 비어 있어요	user_group_id를 입력해요
`USER_GROUP_ROLE_NOT_FOUND`	사업자 관리 역할이 존재하지 않는다	역할을 먼저 설정해요
`USER_GROUP_IS_NOT_CORPORATE`	해당 그룹은 법인 그룹이 아니에요	회원 등록·부서·초대는 기업 그룹(`corporate_type` 2)에서만 돼요

상품 관련 에러

코드	메시지	대처 방법
`PRODUCT_ACTIVE_CANNOT_BE_DELETED`	전시중이거나 판매중인 상품은 삭제할 수 없어요	상품을 비활성화한 후 삭제해요
`PRODUCT_NOT_FOUND`	존재하지 않는 상품이에요	product_id를 확인해요
`PRODUCT_FROZEN`	판매금지된 상품은 편집/저장할 수 없어요	관리자에게 문의해요
`PRODUCT_DENIED`	상품 조회 권한이 없어요	API 인증 권한을 확인해요
`PRODUCT_PRICE_INVALID`	상품가격은 0원 이상이어야 해요	price 값을 확인해요
`PRODUCT_OPTION_DENIED`	상품 옵션이 비활성화된 상태예요	옵션 상태를 확인해요
`PRODUCT_OPTION_NOT_MATCH`	상품 옵션 정보가 없어요	option_id를 확인해요
`INVENTORY_INVALID_QUANTITY`	유효하지 않은 수량이에요	qty 값을 확인해요
`CATEGORY_NOT_OWNED_BY_SELLER`	판매자의 카테고리가 아니에요	다른 프로젝트의 카테고리 ID 를 쓰지 않았는지 확인해요
`CATALOG_NAME_REQUIRED`	카탈로그 이름은 필수예요	`name` 을 넣어요
`CATALOG_PRODUCT_NOT_FOUND`	카탈로그-상품 연결을 찾을 수 없어요	그 카탈로그에 담긴 상품 ID 인지 확인해요
`EX_UID_DUPLICATED`	이미 존재하는 ex_uid를 가진 데이터가 있어요	다른 ex_uid를 사용해요

링크페이 관련 에러

코드	메시지	대처 방법
`INVOICE_PRICE_GT_0`	결제금액이 0보다 커야 해요	price를 0보다 크게 설정해요
`INVOICE_TAX_FREE_GT_0`	면세금액이 설정되면 0보다 커야 해요	tax_free를 0보다 크게 설정하거나 제거해요
`INVOICE_TAX_FREE_LTE_PRICE`	면세금액이 판매금액보다 크면 안돼요	tax_free ≤ price 조건을 확인해요
`INVOICE_TYPE_INVALID`	링크페이 결제 종류가 잘못 선택됐어요	type 값을 확인해요
`INVOICE_NOT_FOUND`	링크페이 정보를 찾을 수 없어요	invoice_id를 확인해요
`INVOICE_DENIED`	조회 권한이 없는 회원세션이에요	올바른 API 키를 사용하고 있는지 확인해요
`INVOICE_TARGET_NOT_FOUND`	링크페이에 등록된 사용자 정보가 없어요	`user.user_id` 를 넣었는지, `member` 라면 부트페이에 등록된 고객인지 확인해요. 로그인 토큰에서 회원을 못 찾을 때도 이 코드예요
`INVOICE_ORDER_DONE_EXPIRED`	기간만료된 청구서예요	새 청구서를 발급해요
`INVOICE_EXPIRED_DATE_INVALID`	만료일이 현재 시간보다 과거예요	expired_at을 미래 시간으로 설정해요
`INVOICE_ITEM_QTY_LT_ZERO`	상품 수량은 0보다 커야 해요	qty를 1 이상으로 설정해요
`INVOICE_PRODUCT_NOT_FOUND`	존재하지 않는 상품이 포함되어 있어요	product_id를 확인해요
`INVOICE_PRODUCT_OPTION_ID_REQUIRED`	옵션이 필요한 상품이 포함되어 있어요	product_option_id를 입력해요
`INVOICE_PRODUCT_OPTION_NOT_FOUND`	존재하지 않는 옵션이 포함되어 있어요	product_option_id를 확인해요
`INVOICE_SUBSCRIPTION_REQUEST_ONLY_ONE`	구독 상품은 하나만 청구서에 포함될 수 있어요	구독 상품을 하나만 포함해요
`INVOICE_PRODUCT_SUBSCRIPTION_DURATION_NOT_FOUND`	존재하지 않는 구독 기간이 포함되어 있어요	duration 값을 확인해요
`INVOICE_PRODUCT_SUBSCRIPTION_DURATION_REQUIRED`	구독 상품은 구독 기간이 필요해요	duration 파라미터를 추가해요
`INVOICE_NEED_USAGE_API_URL`	사용량 기반 구독 상품은 사용량 API URL이 필요해요	usage_api_url을 입력해요
`INVOICE_REQUEST_ID_BLANK`	요청 ID가 필요해요	request_id를 입력해요

주문 관련 에러

코드	메시지	대처 방법
`ORDER_NOT_FOUND`	주문내역을 찾지 못했어요	order_id 또는 order_number를 확인해요
`RECEIPT_ID_BLANK`	receipt_id가 비어 있어요	receipt_id를 입력해요
`ORDER_RECEIPT_STATUS_INVALID`	결제 완료 정보를 수신하지 못했어요	처음부터 결제를 다시 진행해요
`ORDER_CONFIRM_PAYMENT_FAILED`	결제 승인에 실패했어요	결제 정보를 확인 후 재시도해요
`ORDER_RECEIPT_PRICE_INVALID`	요청 금액과 승인 금액이 일치하지 않는다	price 값을 확인해요
`ORDER_CANCEL_ALREADY_COMPLETED`	이미 결제 취소 처리가 됐어요	주문 상태를 먼저 조회해요
`ORDER_PRODUCT_BLANK`	주문한 상품 정보가 없어요	products 파라미터를 확인해요
`ORDER_PRODUCT_NOT_FOUND`	상품 정보가 없어요	product_id를 확인해요
`ORDER_OPTION_NOT_FOUND`	상품 옵션 정보가 없어요	option_id를 확인해요
`ORDER_PRODUCT_NEED_OPTION`	상품에 옵션 선택이 필수예요	option_id를 추가해요
`ORDER_PRODUCT_STOCK_OUT`	상품 재고가 모두 소진됐어요	상품 재고를 확인해요
`ORDER_OPTION_STOCK_OUT`	상품 옵션 재고가 모두 소진됐어요	옵션 재고를 확인해요
`ORDER_SUBSCRIPTION_ONLY`	구독상품은 일반 상품과 함께 구매할 수 없어요	구독상품만 별도로 주문해요
`ORDER_PRICE_NOT_MATCH`	요청 금액과 상품 결제 금액이 일치하지 않는다	price 계산을 확인해요
`ORDER_SUBSCRIPTION_INVALID`	구독결제 정보가 올바르지 않아요	구독 설정을 확인해요
`ORDER_ADDRESS_BLANK`	배송상품은 배송지 정보가 필수예요	address 정보를 입력해요
`ORDER_USER_INVALID`	결제 요청 회원정보가 일치하지 않는다	로그인 세션을 확인해요
`ORDER_CANCEL_PRICE_LT_ZERO`	취소금액이 0보다 작을 수 없어요	cancel_price를 확인해요
`ORDER_CANCEL_PRICE_OVER`	취소 가능 금액보다 취소 요청 금액이 더 커요	남은 취소 가능 금액을 확인해요
`ORDER_CANCEL_CRITICAL_ERROR`	상품 취소시 치명적인 오류가 발생했어요	관리자에 문의해요
`ORDER_DENIED`	주문 정보를 조회할 권한이 없어요	API 인증 권한을 확인해요
`ORDER_STATUS_NOT_CANCELABLE`	취소가 불가능한 주문 상태예요	주문 상태를 확인해요
`ORDER_PRODUCT_ALREADY_CANCELLED`	이미 취소된 상품이에요	주문 상품의 취소 상태를 확인해요
`ORDER_EXPIRED`	주문 기간이 지났다	유효 기간 내에 처리해요
`ORDER_NUMBER_EXIST`	이미 결제가 진행된 주문정보가 있어요	새 주문을 생성해요
`ORDER_GUEST_SUBSCRIPTION_NOT_ALLOWED`	비회원은 구독/멤버십 상품을 구매할 수 없어요	회원가입 후 이용해요
`ORDER_CANCEL_REQUEST_TYPE_METHOD`	취소 요청 정보가 없어요	취소 요청 파라미터를 확인해요
`ORDER_CANCEL_REQUEST_REJECT_UNABLE`	취소 요청 처리가 불가능한 상태예요	요청 상태를 확인해요
`ORDER_CANCEL_REQUEST_REJECT_CRITICAL_ERROR`	취소 철회 중 오류가 발생했어요	관리자에 문의해요
`ORDER_CANCEL_NOT_REQUESTED`	취소 요청 상태가 아니에요	주문의 취소 요청 상태를 확인해요
`ORDER_CANCEL_REQUEST_WITHDRAW_UNABLE`	취소 요청 철회가 불가능해요	요청 상태를 확인해요

구독 관련 에러

코드	메시지	대처 방법
`SUBSCRIPTION_NOT_ACTIVE`	구독계약이 활성화되지 않은 상태예요	구독 상태를 확인하거나 관리자에 문의해요
`SUBSCRIPTION_PAYMENT_CYCLE_TYPE_INVALID`	잘못 설정된 결제 주기예요	구독상품의 결제 주기를 확인해요
`SUBSCRIPTION_TRANSACTION_NOT_READY`	회차 구독결제가 이미 결제되었거나 만료된 상태예요	관리자에 문의해요
`SUBSCRIPTION_TRANSACTION_PAYMENT_ERROR`	구독결제가 실패했어요	결제 수단을 확인하거나 관리자에 문의해요
`SUBSCRIPTION_DENIED`	구독 계약 정보를 조회할 권한이 없어요	API 인증 권한을 확인해요
`SUBSCRIPTION_WALLET_BLANK`	구독 결제를 위한 빌링키가 등록되지 않았다	결제 수단을 먼저 등록해요
`SUBSCRIPTION_ADJUSTMENT_NOT_FOUND`	구독결제 조정 정보를 찾을 수 없어요	adjustment_id를 확인해요
`SUBSCRIPTION_ADJUSTMENT_PAYMENT_COMPLETED`	이미 결제가 완료된 회차예요	미결제 회차에 대해서만 조정해요
`SUBSCRIPTION_ADJUSTMENT_DUPLICATE`	동일 회차에 같은 유형의 조정이 이미 있어요	기존 조정을 확인해요
`SUBSCRIPTION_ADJUSTMENT_DURATION_INVALID`	회차가 지정되지 않았다	cycle 파라미터를 입력해요
`SUBSCRIPTION_ADJUSTMENT_NEGATIVE_PRICE`	조정으로 인해 결제 금액이 음수가 돼요	조정 금액을 확인해요
`ORDER_SUBSCRIPTION_ALREADY_PROCESSED`	이미 처리된 구독이에요	구독의 현재 상태를 조회해요
`ORDER_SUBSCRIPTION_PURCHASE_PRICE_REQUIRED`	구독 구매 금액은 필수예요	금액을 넣어요
`ORDER_SUBSCRIPTION_REQUEST_TYPE_INVALID`	구독 요청 타입이 유효하지 않아요	`request_type` 값을 확인해요
`ORDER_SUBSCRIPTION_ALREADY_PAUSE`	이미 일시정지가 진행된 구독이에요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_EXPECTED_RESUME_AT_INVALID`	재개 시각이 현재보다 과거이거나 1년 이후예요	재개 예정 시각을 지금부터 1년 안으로 넣어요
`SUBSCRIPTION_TERMINATION_FEE1_INVALID`	중도해지 수수료가 유효하지 않아요	수수료 값을 확인해요
`SUBSCRIPTION_TERMINATION_FEE2_INVALID`	마지막 회차 환불금액이 유효하지 않아요	환불 금액을 확인해요
`SUBSCRIPTION_TERMINATION_FEE3_INVALID`	최종 수수료가 유효하지 않아요	최종 수수료 값을 확인해요

수시결제(재결제 키) 에러

코드	메시지	대처 방법
`CHARGE_KEY_NOT_FOUND`	재결제 키를 찾을 수 없어요	키 값을 다시 확인해요
`CHARGE_KEY_USER_MISMATCH`	재결제 키의 소유 회원 정보가 일치하지 않아요	키를 발급받은 회원인지 확인해요
`CHARGE_KEY_REVOKED`	해지된 재결제 키예요	결제창에서 다시 동의받아 새 키를 발급받아요
`CHARGE_KEY_WALLET_INVALID`	재결제 키에 연결된 결제 지갑이 삭제되었거나 만료됐어요	결제수단을 다시 등록해요
`CHARGE_KEY_PRICE_OVER_LIMIT`	결제 금액이 재결제 키의 1회 결제 상한을 초과했어요	금액을 상한 이내로 줄여요
`CHARGE_KEY_SUBSCRIPTION_INVALID`	구독이 해지되었거나 상품이 결제할 수 없는 상태예요	구독·상품 상태를 확인해요
`CHARGE_KEY_RATE_LIMITED`	키 검증 실패가 누적되어 일시적으로 잠겼어요	잠시 후 다시 시도해요

구독 설정 에러

코드	메시지	대처 방법
`INVALID_SUBSCRIPTION_SETTING`	올바른 구독설정이 아니에요	구독 설정 ID 를 확인해요
`SUBSCRIPTION_SETTING_TYPE_INVALID`	구독 유형 설정이 잘못되었어요	구독 유형을 설정해요
`SUBSCRIPTION_SETTING_PREPAID_ON_USAGE_NOT_ABLE`	사용량 과금 구독은 선불 결제를 설정할 수 없어요	후불결제로 바꿔요
`SUBSCRIPTION_SETTIGN_NEED_USAGE_API_URL`	사용량 과금 구독은 사용량 조회 API URL 이 필요해요	`usage_api_url` 을 넣어요 (코드 이름의 `SETTIGN` 철자가 실제 응답 그대로예요)
`SUBSCRIPTION_SETTING_FREE_TRIAL_DAY_EXCEED`	무료체험 기간은 최대 365일까지예요	체험 일수를 줄여요
`SUBSCRIPTION_SETTING_USAGE_CYCLE_MONTHLY_ONLY`	사용량 과금 구독은 월 단위 결제 주기만 설정할 수 있어요	결제 주기를 월 단위로 바꿔요

구독 쿠폰 에러

코드	메시지	대처 방법
`COUPON_ALREADY_USED`	이미 사용된 쿠폰이에요	다른 쿠폰을 써요
`COUPON_TYPE_NOT_APPLICABLE_TO_SUBSCRIPTION`	구독에 적용할 수 없는 쿠폰 유형이에요	구독용 쿠폰인지 확인해요
`COUPON_NOT_APPLICABLE_FOR_USAGE_BASED_SUBSCRIPTION`	종량제 구독에는 쿠폰을 적용할 수 없어요	—
`COUPON_SHIPPING_NOT_APPLICABLE_FOR_RECURRING_DELIVERY`	정기배송 구독에는 배송비 쿠폰을 적용할 수 없어요	—

구독 청구 관련 에러

코드	메시지	대처 방법
`ORDER_SUBSCRIPTION_BILL_NOT_FOUND`	회차 구독결제 청구 정보를 찾을 수 없어요	bill_id를 확인해요
`ORDER_SUBSCRIPTION_BILL_STATUS_NOT_DONE`	회차 구독결제 청구 상태가 완료되지 않았다	결제 완료 후 시도해요
`ORDER_SUBSCRIPTION_BILL_UNABLE_EXECUTE_PAYMENT`	결제할 수 없는 상태예요	청구 상태를 확인해요
`ORDER_SUBSCRIPTION_BILL_EXIST`	이미 청구가 있어요	기존 청구를 확인해요
`ORDER_SUBSCRIPTION_BILL_PAYMENT_TIME_UNCHANGEABLE`	결제예정시간을 변경할 수 없어요	변경 가능한 상태인지 확인해요
`ORDER_SUBSCRIPTION_BILL_UNCHANGEABLE_ALREADY_PAY`	이미 결제된 주문이에요	결제 상태를 확인해요
`ORDER_SUBSCRIPTION_BILL_PAYMENT_TIME_INVALID`	유효한 결제시간이 아니에요	결제 시간을 현재 이후로 설정해요

구독 취소·해지 관련 에러

코드	메시지	대처 방법
`ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_NOT_FOUND`	회차 구독결제 취소 요청 내역을 찾을 수 없어요	취소 요청 ID를 확인해요
`ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_ALREADY_COMPLETED`	해당 회차 구독결제는 이미 취소 완료됐어요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_ALREADY_REQUESTED`	이미 취소 신청이 완료된 건이에요	기존 취소 요청 상태를 확인해요
`ORDER_SUBSCRIPTION_NOT_FOUND`	구독결제 건을 찾을 수 없어요	order_subscription_id를 확인해요
`ORDER_SUBSCRIPTION_TERMINATE_UNABLE`	이미 해지되었거나 해지할 수 없는 구독 상태예요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_PAUSE_UNABLE`	이 구독은 일시정지를 지원하지 않는 정책이에요	구독 정책을 확인해요
`ORDER_SUBSCRIPTION_RESUME_UNABLE`	현재 일시정지 상태가 아니므로 재개할 수 없어요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_TERMINATE_CANNOT_ABLE`	구독해지를 승인할 수 없는 상태예요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_REJECT_REASON_BLANK`	구독 거절 시 거절 사유는 필수예요	reason 파라미터를 입력해요

구독 고급 기능 에러

코드	메시지	대처 방법
`SUBSCRIPTION_PAUSE_NOT_ALLOWED`	일시정지 기능이 비활성화되어 있어요	구독 설정에서 일시정지를 활성화해요
`SUBSCRIPTION_PAUSE_COUNT_EXCEEDED`	일시정지 횟수가 초과됐어요	최대 일시정지 횟수를 확인해요
`SUBSCRIPTION_PAUSE_DURATION_TOO_LONG`	일시정지 기간이 최대 기간을 초과했어요	최대 일시정지 기간 이내로 설정해요
`ORDER_SUBSCRIPTION_PAUSE_APPROVE_ERROR`	일시정지 승인을 할 수 없는 상태예요	요청 상태를 확인해요
`ORDER_SUBSCRIPTION_PAUSE_REJECT_ERROR`	일시정지 거부를 할 수 없는 상태예요	요청 상태를 확인해요
`ORDER_SUBSCRIPTION_PAUSE_REASON_BLANK`	일시정지 거절 사유가 비어 있어요	reason 파라미터를 입력해요
`SUBSCRIPTION_TRANSFER_NOT_ALLOWED`	이전/승계 기능이 비활성화되어 있어요	구독 설정에서 이전/승계를 활성화해요
`ORDER_SUBSCRIPTION_TRANSFER_REQUEST_DUPLICATE`	이미 대기 중인 이전/승계 요청이 있어요	기존 요청 처리를 기다린다
`ORDER_SUBSCRIPTION_PURCHASE_REQUEST_DUPLICATE`	이미 대기 중인 중도인수 요청이 있어요	기존 요청 처리를 기다린다
`SUBSCRIPTION_TERMINATION_NOT_ALLOWED`	중도해지 요청을 할 수 없는 상태예요	구독 상태를 확인해요
`SUBSCRIPTION_TERMINATION_REASON_REQUIRED`	중도해지 사유를 입력해야 해요	reason 파라미터를 입력해요
`ORDER_SUBSCRIPTION_PURCHASE_STATUS_INVALID`	중도인수가 가능한 상태가 아니에요	구독 상태를 확인해요
`ORDER_SUBSCRIPTION_PAYMENT_DATE_INVALID`	유효하지 않는 결제일이에요	다른 일자로 선택해요
`ORDER_SUBSCRIPTION_PAYMENT_DATE_TODAY_UNCHANGEABLE`	당일 결제예정건은 변경할 수 없어요	다음날 이후로 변경해요
`ORDER_SUBSCRIPTION_REQUEST_HISTORY_NOT_FOUND`	계약변경 요청 내역을 찾을 수 없어요	request_history_id를 확인해요
`ORDER_SUBSCRIPTION_REQUEST_HISTORY_CANNOT_WITHDRAW`	계약변경 요청을 취소할 수 없어요	요청 상태를 확인해요
`ORDER_SUBSCRIPTION_REQUEST_HISTORY_ALREADY_PROCESSED`	이미 처리된 요청이에요	새로운 요청을 생성해요
`SUBSCRIPTION_RESUME_REASON_REQUIRED`	재개 사유를 입력해야 해요	reason 파라미터를 입력해요

장바구니 관련 에러

코드	메시지	대처 방법
`CART_NOT_FOUND`	장바구니를 찾을 수 없어요	cart_id를 확인해요
`CART_SUBSCRIBE_PRODUCT_NOT_ALLOWED`	구독 상품은 장바구니에 담을 수 없어요	구독 상품은 직접 주문해요
`CART_PRODUCT_OPTION_REQUIRED`	상품 옵션 선택이 필요해요	option_id를 입력해요
`CART_FULL`	장바구니가 가득 찼다 (비회원 최대 50개)	기존 아이템을 삭제해요
`CART_ITEM_NOT_FOUND`	장바구니 아이템을 찾을 수 없어요	item_id를 확인해요
`CART_ITEM_UNAVAILABLE`	장바구니 아이템을 사용할 수 없어요	상품이 삭제/변경되었는지 확인해요
`CART_MERGE_FAILED`	장바구니 병합에 실패했어요	재시도해요
`CART_EMPTY`	장바구니가 비어있어요	상품을 먼저 담는다
`CART_HAS_UNAVAILABLE_ITEMS`	장바구니에 구매 불가능한 상품이 포함되어 있어요	불가 상품을 제거해요
`PRODUCT_NOT_AVAILABLE`	상품을 구매할 수 없어요 (삭제 또는 비활성화됨)	상품 상태를 확인해요
`CART_ITEM_STOCK_OUT`	장바구니 아이템의 재고가 부족해요	수량을 줄이거나 재고를 확인해요

웹훅 관련 에러

코드	메시지	대처 방법
`WEBHOOK_URL_BLANK`	웹훅 URL을 입력해요	웹훅 테스트 발송에 `webhook_url` 을 넘기거나 프로젝트에 웹훅을 등록해요
`TEST_WEBHOOK_ORDER_NOT_FOUND`	테스트용 주문을 찾을 수 없어요	부트페이에 문의해요

알림톡 관련 에러

알림톡·알림톡 발송·운영 문서의 에러표는 숫자 코드로 적혀 있어요. API 응답의 error_code 에는 숫자가 아니라 아래 이름이 문자열로 와요.

숫자	응답 `error_code`	메시지
`-48`	`INVALID_PARAMETER`	필수 파라미터를 입력해주세요 (`API_PARAM_INVALID` 가 아니라 이 이름으로 와요)
`500`	`STORAGE_NOT_IMAGE_FILE`	업로드된 파일이 이미지 파일이 아니에요
`501`	`STORAGE_IMAGE_BLANK`	이미지 파일이 없어요
`505`	`STORAGE_IMAGE_INVALID_SIZE`	이미지 사이즈가 잘못되었어요
`508`	`STORAGE_IMAGE_UPLOAD_FAILED`	이미지 업로드에 실패했어요
`3010`	`MESSAGE_SDK_TOKEN_FAILED`	메시지 SDK 토큰 요청에 실패했어요
`3012`	`KAKAO_SENDER_REQUEST_FAILED`	카카오 발신 프로필 요청에 실패했어요
`3013`	`KAKAO_TEMPLATE_REQUEST_FAILED`	카카오 템플릿 요청에 실패했어요
`3015`	`TEMPLATE_NOT_FOUND`	알림톡 템플릿을 찾을 수 없어요
`3016`	`TEMPLATE_NOT_APPROVED`	승인되지 않은 알림톡 템플릿이에요
`3017`	`TEMPLATE_VARIABLE_MISSING`	템플릿 변수가 누락되었거나 규격에 맞지 않아요
`3018`	`SENDER_NOT_VERIFIED`	검증되지 않은 발신 프로필이에요
`3019`	`TEMPLATE_CODE_DUPLICATED`	이미 등록된 알림톡 템플릿 코드예요
`3020`	`SENDER_BLOCKED`	차단된 발신 프로필이에요
`3021`	`RECIPIENT_OPTED_OUT`	수신자가 알림톡 수신을 거부했어요
`3022`	`RATE_LIMIT_EXCEEDED`	발송 한도를 초과했어요
`3023`	`SEND_NOT_CANCELABLE`	취소할 수 없는 발송 상태예요
`3024`	`SENDER_NOT_LINKED`	연결된 발신 프로필이 없어요
`3025`	`MESSAGE_RECEIPT_NOT_FOUND`	발송 기록을 찾을 수 없어요
`3027`	`TEMPLATE_NAME_DUPLICATED`	같은 발신프로필에 이미 있는 템플릿 이름이에요
`3028`	`WEBHOOK_URL_INVALID`	웹훅 수신 URL 형식이 올바르지 않아요 (https 주소만 받아요)
`3029`	`WEBHOOK_NOT_CONFIGURED`	웹훅 수신 URL 이 설정되어 있지 않아요
`3031`	`EXPORT_LIMIT_EXCEEDED`	내보내기 건수가 너무 많아요
`3503`	`NOTIFICATION_NEED_PAYMENT`	부트페이 사용량 정기구독 서비스 이용이 필요해요
`11100`	`SERVICE_PAYMENT_BLOCKED`	서비스 이용료 미납으로 서비스 이용이 제한되었어요
`11101`	`MESSAGE_PREPAID_NOT_CHARGED`	발송 요금을 충전한 뒤에 이용할 수 있어요 (선불 요금제의 첫 충전 전)
`11103`	`ALIMTALK_API_MOVED`	알림톡 API 주소가 바뀌었어요. `https://message.bootapi.com/alimtalk` 로 요청해 주세요 (옛 주소 `/v1/alimtalk/*` 의 410 응답)

벌크 발송 응답의 건별 결과 receipts[].code 는 위 표의 숫자가 정수 그대로 와요 (예: 발송 제외 목록에 걸려 건너뛴 건은 3021). 이름 문자열로 오는 것은 요청 전체가 거절될 때의 error_code 뿐이에요.

코드표 (Enum)

주문 상태, 취소 요청 상태, 링크페이 상태, 구독 상태, 구독 회차 상태 등 코드값은 별도 페이지로 분리됐어요.

→ 커머스 Enum