본문으로 건너뛰기

크레딧과 사용량

aicon API로 쿠폰을 발급하거나 발송하면 쿠폰 금액만큼 크레딧이 차감됩니다. 크레딧 잔액과 사용량 한도를 이해하면 안정적으로 서비스를 운영할 수 있습니다.

크레딧 체계​

크레딧은 원(KRW) 단위의 선불 잔액입니다.

충전 (charge) ──→ 잔액 (balance) ──→ 차감 (deduct)
                       ↑
                  환불 (refund)
항목설명
balance현재 사용 가능한 잔액
totalCharged누적 충전 금액
totalConsumed누적 소비 금액 (환불 차감 후)

크레딧은 언제 차감되나​

크레딧은 발급 요청 시점에 즉시 차감됩니다. PIN 발급과 MMS 발송 모두 동일합니다.

요청 → 크레딧 차감 → 벤더 호출 → 성공 / 실패
                                    ↓
                              실패 시 자동 환불
  • 성공: 차감된 크레딧이 그대로 유지됩니다.
  • 실패: 벤더 측 오류 등으로 발급이 실패하면 차감된 크레딧이 자동으로 환불됩니다. 별도 요청이 필요 없습니다.
  • 취소: 발급 취소 시에도 크레딧이 환불됩니다.
테스트 키에서는 차감되지 않습니다

test_sk_ 키로 요청하면 크레딧이 차감되지 않습니다. 실제 과금은 live_sk_ 키를 사용할 때만 발생합니다.

잔액 부족​

잔액이 쿠폰 금액보다 적으면 발급이 거부됩니다.

{
  "status": 402,
  "code": "CREDIT_INSUFFICIENT_BALANCE",
  "message": "크레딧 잔액이 부족합니다."
}

잔액은 잔액 조회 API로 확인할 수 있습니다.

사용량 한도​

일일 또는 월간 사용 금액에 상한선을 설정할 수 있습니다. 예상치 못한 대량 발급으로 크레딧이 소진되는 것을 방지하는 안전장치입니다.

한도기준초과 시
일일 한도KST 기준 00:00 ~ 23:59429 USAGE_DAILY_LIMIT_EXCEEDED
월간 한도KST 기준 매월 1일 ~ 말일429 USAGE_MONTHLY_LIMIT_EXCEEDED

한도는 사용량 한도 설정 API로 설정하거나 해제할 수 있고, 현재 사용량은 사용량 조회 API로 확인할 수 있습니다.

// 사용량 조회 응답 예시
{
  "daily": {
    "period": "2026-04-15",
    "usedAmount": 350000,
    "limitAmount": 1000000,
    "remainingAmount": 650000
  },
  "monthly": {
    "period": "2026-04",
    "usedAmount": 2500000,
    "limitAmount": null,
    "remainingAmount": null
  }
}

limitAmount가 null이면 한도가 설정되지 않은 것입니다.

사용량 한도와 Rate Limit​

둘 다 429 상태 코드를 반환하지만, 역할이 다릅니다.

사용량 한도Rate Limit
제한 기준사용 금액 (원)요청 횟수 (건/초)
기간일일 / 월간초 단위
목적비용 통제서버 보호
에러 코드USAGE_DAILY_LIMIT_EXCEEDEDCOMMON_RATE_LIMIT_EXCEEDED
해결 방법한도 상향 또는 다음 기간까지 대기잠시 후 재시도

잔액 부족 vs 한도 초과​

잔액 부족한도 초과
HTTP 상태402429
의미충전한 크레딧이 모두 소진됨설정한 기간별 한도에 도달함
해결 방법크레딧 충전한도 상향 또는 다음 기간까지 대기