오류 코드

이 문서는 결제 요청·승인·취소 과정에서 발생하는 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 요청 금액과 승인 금액 불일치

흔한 원인​: 프론트엔드에서 보낸 금액과 서버 DB의 금액이 달라요. 할인·쿠폰 적용 후 금액 동기화를 빠뜨린 경우가 가장 많아요.

// 잘못된 예 — 프론트엔드 금액을 그대로 신뢰
const price = req.body.price

// 올바른 예 — 서버 DB에서 직접 계산한 금액과 결제 금액 비교
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

5AUTHENTICITY_TOKEN_EXPIRE 인증 오류

흔한 원인​: 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