오류 코드

이 문서는 결제 요청·승인·취소 과정에서 발생하는 PG 연동 에러 코드를 분류별로 정리해요. API 호출이 실패하면 응답의 error_code 를 먼저 보고, 이 표에서 원인과 대처법을 찾아요.

자주 만나는 에러 TOP 6

연동 중 가장 많이 마주치는 에러와 해결법이에요.

1APP_AT_AUTHORIZE_HEADER_BLANK Authorization 헤더 누락/오류

흔한 원인​: Basic Auth 헤더가 없거나 형식이 올바르지 않아요.

// 올바른 예 — SDK 사용 시 자동 처리
Bootpay.setConfiguration({
    client_key: 'YOUR_CLIENT_KEY',
    secret_key: 'YOUR_SECRET_KEY'
})
const receipt = await Bootpay.receiptPayment(receiptId)

// 직접 호출 시 — Basic Auth 헤더 추가
const BASIC_AUTH = 'Basic ' + btoa(`${CLIENT_KEY}:${SECRET_KEY}`)javascript

2RC_PRICE_MISMATCH PG 승인 금액과 부트페이 기록 금액 불일치

흔한 원인​: 가맹점 DB와의 비교에서 나는 에러가 아니에요. 부트페이가 PG(토스·라이트페이)에 결제 건을 조회했을 때 PG가 알려준 승인 금액​​과 부트페이에 기록된 결제 금액​​이 다를 때 발생해요. 가맹점 코드로 고칠 수 있는 상황이 아니니 receipt_id와 함께 관리자에 문의해요.

승인 요청 금액이 최초 요청 금액과 다른 경우는 별도 코드로 내려와요.

가맹점 주문 금액과의 대조는 부트페이가 대신해 주지 않아요. 서버에서 직접 비교해요.

// 서버 DB에서 계산한 금액과 결제 조회 결과를 비교
const receipt = await Bootpay.receiptPayment(receiptId)
const order = await db.orders.findByPk(orderId)

if (receipt.price !== order.total_amount) {
    // 금액 불일치 → 결제 취소 또는 주문 보류
}javascript

3APP_SK_NOT_MATCHED Secret KEY 불일치

흔한 원인​: 테스트 키와 운영 키를 헷갈렸거나 .env 에 잘못된 키를 복사한 경우예요.

• 관리자 > 개발자 설정 > API 연동키 (결제) 에서 Private Key 를 다시 복사해요.
• 테스트·운영 환경의 키가 다르면 BOOTPAY_SANDBOX 설정을 확인해요.

4RC_ALREADY_CANCELLED 이미 취소 처리됨

흔한 원인​: 웹훅과 프론트엔드에서 동시에 취소 요청을 보내거나 취소 전에 결제 상태를 확인하지 않는 경우예요.

// 올바른 예 — 취소 전 결제 상태와 가맹점 DB 상태 확인
const receipt = await Bootpay.receiptPayment(receiptId)
const order = await db.orders.findByPk(orderId)

if (receipt.status === 20 || order.status === 'refunded') {
    return res.json({ error: '이미 취소된 결제입니다' })
}
// 취소 진행...javascript

5APP_CLIENT_KEY_NOT_FOUND / APP_KEY_CHAIN_EXPIRED 연동키 오류

흔한 원인​: Client Key 로 연동키를 찾지 못했거나(APP_CLIENT_KEY_NOT_FOUND), Client Key 와 Secret Key 의 짝이 맞지 않거나(APP_SK_NOT_MATCHED), 발급받은 연동키의 유효기간이 지난 경우(APP_KEY_CHAIN_EXPIRED)예요.

• 관리자 > 개발자 설정 > API 연동키 에서 Client Key·Private Key 와 만료일​​을 함께 확인해요.
• Client Key 와 Secret Key 는 반드시 같은 연동키에서 발급된 짝으로 보내야 해요.

6RC_NOT_FOUND 영수증 정보 없음

흔한 원인​: receipt_id 오타, 다른 프로젝트의 결제 건 조회, 테스트·운영 환경 혼동 중 하나예요.

에러 응답 형식

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

{
  "error_code": "RC_ALREADY_CANCELLED",
  "message": "요청하신 결제는 이미 취소처리가 되었습니다."
}json

인증 관련 에러 {#인증-관련-에러}

공통 에러

결제 관련 에러

결제 요청, 승인, 취소 과정에서 발생하는 에러예요.

정기결제(빌링) 관련 에러

계좌자동이체 관련 에러

본인인증 관련 에러

예약결제 관련 에러

에스크로 관련 에러

현금영수증 관련 에러

프론트엔드 에러 코드

서버 오류 코드

부트페이 서버 처리 중 발생하는 오류예요.

코드표 (Enum)

PG사·결제수단·카드사·은행·통화 등 코드값은 별도 페이지에서 봐요.

→ 결제연동 Enum