API 규약

에러 응답

표준 에러 형식과 HTTP 상태, 에러 코드별 원인과 해결 방법.

에러는 모든 엔드포인트에서 같은 모양으로 옵니다. 분기는 error.code 로 하세요. message 는 사람이 읽는 한국어 문구라 바뀔 수 있습니다.

형식

{
  "error": {
    "code": "UNPROCESSABLE",
    "message": "확정된 청구서만 결제할 수 있습니다. 현재 상태: 작성중",
    "detail": {"invoice_status": "DRAFT"},
    "request_id": "req_4f1c9a2b7d3e5f60a1b2c3d4"
  }
}

• request_id 는 응답 헤더 X-Request-Id 에도 있습니다. 성공 응답에도 붙습니다. 로그에 남겨 두고, 문의할 때 알려 주세요.
• detail 은 코드마다 내용이 다릅니다. 비어 있으면 {} 입니다.
• 결제사가 보낸 원래 코드는 그대로 내보내지 않습니다. 결제사를 바꿔도 가맹점 코드가 깨지지 않게 하기 위해서입니다.

HTTP 상태

에러 코드

형식 오류(400) 예

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "요청 값이 올바르지 않습니다.",
    "detail": {"fields": {"phone": ["휴대전화 번호를 확인해 주세요. 숫자 9~11자리로 입력합니다."]}},
    "request_id": "req_9a8b7c6d5e4f3a2b1c0d9e8f"
  }
}

detail.fields 의 모양은 엔드포인트에 따라 조금 다릅니다(필드 이름 → 문구 목록, 또는 검증 항목 목록). 화면에 그대로 보여 주기보다 로그로 남겨 개발 중에 고치는 용도입니다.

422 의 사유 코드

일부 API 는 422 UNPROCESSABLE 에 detail.reason 을 함께 줍니다. 사유 코드 목록은 각 문서에 있습니다.

• 수시결제 동의 — LIMIT_ONCE · LIMIT_MONTH · CONSENT_REVOKED · CARD_UNAVAILABLE 등
• 월별 청구 금액 — NOT_VARIABLE · NOT_A_ROUND · ROUND_LOCKED · INVALID_DATE 등

결제 승인(POST /api/v1/payments)이 결제사로 나가기 전에 막히면 422 UNPROCESSABLE 의 detail.kind 로 원인을 구분합니다.

결제 거절은 에러가 아닙니다

카드 한도 초과·정지 카드 같은 거절은 정상적인 처리 결과입니다. HTTP 200 으로 오고, 결제 객체의 status 가 FAILED, failure_reason 에 빌링플러스 표준 사유가 들어 있습니다.

{
  "id": 8812,
  "payment_no": "P-2026-1028-0007",
  "status": "FAILED",
  "amount": 29900,
  "failure_reason": "LIMIT_EXCEEDED",
  "failure_message": "한도초과",
  "approved_at": null
}