API 레퍼런스

에러 코드

게이트웨이 RESULT_CODE, PG 결과 코드, 청구 서버 result_code와 조치 방법입니다.

게이트웨이 result_data.RESULT_CODE

오류도 HTTP 200으로 옵니다. 최상위 result_code는 -10, result_msg에 사유가 담기고 result_data.RESULT_CODE가 아래 코드입니다.

코드	메시지	발생 조건	조치
`0000`	정상적으로 처리 되었습니다.	성공	—
`3001`	API_SIGN 오류입니다.	서명 불일치	5개 값 순서·`TRANS_AT` 동일값·`API_KEY`(테스트/운영) 확인
`4001`	이미 처리된 결제요청입니다.	같은 `TRANS_SEQNO` 재생성	새 거래번호로 생성. 재시도 로직이 거래번호를 재사용하는지 확인
`4002`	필수 정보가 누락되었습니다.	필수 필드 누락	요청 필드 확인
`4003`	결제요청 정보가 없습니다.	조회 대상 없음	거래번호·`PLATFORM_CODE`·`STORE_CODE` 조합 확인
`4004`	결제취소(삭제) 요청 정보가 없습니다.	취소 대상 없음 또는 카드사 취소 실패(`CANCEL_FAIL`)	조회 후 상태 확인, 실패면 카리페이 문의
`4005`	플랫폼코드, 가맹점코드가 올바르지 않습니다.	코드 오타·미발급·조합 불일치	발급 정보 확인
`4006`	가맹점의 온라인 단말(CAT) 정보가 없습니다.	가맹점 설정 미완료	카리페이 문의
`4008`	카드 단말에서 승인된 결제는 승인한 키오스크에서 취소해 주세요.	단말 승인 건 API 취소	단말에서 취소
`5001`	정상적으로 작업이 완료되지 않았습니다.	처리 중 오류	재시도 후 지속 시 문의
`9999`	결제요청 중 오류가 발생하였습니다.	알 수 없는 오류	문의

검증 오류는 result_msg가 MOBILE_NO: must match "^\d{10,11}$"처럼 필드: 사유로 옵니다.

코드	의미	조치
`0`	성공	—
`-1`	토큰이 없습니다	`x-access-token` 헤더 확인
`-2`	토큰이 만료되었습니다	`POST /app/v1/auth/refresh`로 갱신 후 재시도
`-3`	파라미터 누락	요청 본문 확인
`-4`	사용자 정의 오류	`result_msg` 확인
`-10`	처리 오류	`result_msg` 확인 (예: 포인트 부족, 권한 없음, 청구서 없음)

자주 보는 result_msg:

메시지	원인
`포인트가 부족하여 청구서를 보낼 수 없습니다.`	발송 포인트 부족
`청구 금액은 최소 100원 이상이어야 합니다.`	금액 오류
`아직 발송되지 않은 청구서입니다.`	미발송 건 재발송 시도
`재발송할 수 없는 청구서입니다.`	수납완료·취소·삭제 건 재발송
`청구서에 대한 권한이 없습니다.`	다른 가맹점의 청구서
`같은 requestId(...)로 다른 내용의 청구서를 보낼 수 없습니다.`	멱등 키 재사용 오류

발송 이력 상태 갱신 시 알리고 결과가 표시됩니다.

결과	의미	조치
`0`	성공	—
`M`	템플릿 없음	카리페이 설정 문제. 문의
`U`	템플릿 불일치	카리페이 설정 문제. 문의
수신 불가·차단	카카오 미가입, 채널 차단	발송 수단을 `SMS` 또는 `ALIMTALK_THEN_SMS`로

문서에 없는 내용이나 오류는 bellight@goatheaven.com 또는 지원 문의로 알려주세요.