에러 코드

aicon API의 모든 에러 응답은 아래 형식을 따릅니다.

{
  "status": 400,
  "code": "ERROR_CODE",
  "message": "에러 설명 메시지",
  "detail": { ... },
  "requestId": "req_01H..."
}

공통 에러

모든 API 엔드포인트에서 발생할 수 있는 에러입니다.

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
AUTH_INVALID_API_KEY	401	유효하지 않은 API 키입니다.	Invalid API key.	Secret Key가 올바른지 확인하세요. test_sk_ 또는 live_sk_ 로 시작해야 합니다.
COMMON_INVALID_REQUEST	400	요청 형식이 올바르지 않습니다.	Invalid request.	요청 Body, Query 파라미터 형식을 확인하세요.
COMMON_RATE_LIMIT_EXCEEDED	429	요청 한도를 초과했습니다.	Rate limit exceeded.	잠시 후 다시 요청하세요. 지속 시 담당자에게 문의하세요.
COMMON_HTTPS_REQUIRED	403	HTTPS 요청만 허용됩니다.	HTTPS requests are required.	HTTP 대신 HTTPS를 사용하세요.
COMMON_INTERNAL_ERROR	500	일시적인 오류가 발생했습니다.	An internal error occurred.	잠시 후 재시도하세요. 지속 시 담당자에게 문의하세요.
COMMON_NOT_IMPLEMENTED	501	아직 구현되지 않은 기능입니다.	This endpoint is not implemented yet.	해당 엔드포인트는 아직 제공되지 않습니다.

카탈로그

GET /v1/brands, GET /v1/categories, GET /v1/coupons, GET /v1/coupons/:couponId

브랜드 목록 조회와 카테고리 목록 조회에는 전용 에러 코드가 없습니다. 공통 에러를 참고하세요.

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COUPON_INVALID_CURSOR	400	커서 형식이 올바르지 않습니다.	Invalid cursor format.	이전 목록 응답의 nextCursor 값을 그대로 전달하세요.

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COUPON_INVALID_COUPON_ID	400	쿠폰 ID 형식이 올바르지 않습니다.	Invalid coupon ID format.	couponId는 cpn_ 접두사로 시작하는 ULID 형식이어야 합니다.
COUPON_NOT_FOUND	404	쿠폰을 찾을 수 없습니다.	Coupon not found.	couponId가 정확한지, 해당 쿠폰이 고객사에 할당되었는지 확인하세요.

쿠폰 발송

POST /v1/coupons/issued/send

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COMMON_INVALID_IDEMPOTENCY_KEY	400	멱등키 형식이 올바르지 않습니다.	Invalid idempotency key format.	Idempotency-Key 헤더에 UUID v4 형식의 값을 사용하세요.
COMMON_IDEMPOTENCY_KEY_IN_PROGRESS	409	동일한 멱등키 요청이 처리 중입니다.	Request with the same idempotency key is in progress.	이전 요청 처리가 완료될 때까지 기다린 후 재시도하세요.
COMMON_IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST	409	동일한 멱등키로 다른 요청 본문을 사용할 수 없습니다.	The same idempotency key cannot be reused with a different request.	새 요청에는 새 멱등키를 생성하세요.
CREDIT_INSUFFICIENT_BALANCE	402	크레딧 잔액이 부족합니다.	Insufficient credit balance.	콘솔에서 크레딧 잔액을 확인하고 충전하세요.
USAGE_DAILY_LIMIT_EXCEEDED	429	일일 사용 한도를 초과했습니다.	Daily usage limit exceeded.	콘솔에서 일일 사용 한도를 확인하세요. 한도 상향이 필요하면 관리자에게 문의하세요.
USAGE_MONTHLY_LIMIT_EXCEEDED	429	월간 사용 한도를 초과했습니다.	Monthly usage limit exceeded.	콘솔에서 월간 사용 한도를 확인하세요. 한도 상향이 필요하면 관리자에게 문의하세요.
COUPON_INVALID_COUPON_ID	400	쿠폰 ID 형식이 올바르지 않습니다.	Invalid coupon ID format.	couponId는 cpn_ 접두사로 시작하는 ULID 형식이어야 합니다.
COUPON_NOT_FOUND	404	쿠폰을 찾을 수 없습니다.	Coupon not found.	couponId가 정확한지, 해당 쿠폰이 고객사에 할당되었는지 확인하세요.
COUPON_SEND_INVALID_COUPON	400	발송을 지원하지 않는 쿠폰입니다.	This coupon does not support sending.	카탈로그 API에서 capabilities에 "SEND"가 포함된 쿠폰만 발송 가능합니다.
COUPON_SEND_COUPON_NOT_AVAILABLE	400	현재 발송할 수 없는 쿠폰입니다.	This coupon is not available for sending.	쿠폰 상태를 확인하세요. 판매 중지 등의 이유로 발송이 불가능할 수 있습니다.
COUPON_SEND_INVALID_PHONE	400	수신자 전화번호 형식이 올바르지 않습니다.	Invalid receiver phone number format.	올바른 전화번호를 입력하세요.
COUPON_SEND_INVALID_SENDER_NUMBER	400	발신번호 형식이 올바르지 않습니다.	Invalid sender number format.	올바른 발신번호를 입력하거나, 생략하여 기본값을 사용하세요.
COUPON_SEND_INVALID_MESSAGE	400	메시지 형식이 올바르지 않습니다.	Invalid message format.	메시지 본문(content)은 필수이며, 벤더별 바이트/글자수 제약을 확인하세요.
COUPON_SEND_ORDER_ID_CONFLICT	409	이미 사용된 orderId입니다.	The orderId is already used.	다른 orderId를 사용하거나, 기존 발송 결과를 조회 API로 확인하세요.

PIN 발급

POST /v1/coupons/issued/pin

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COMMON_INVALID_IDEMPOTENCY_KEY	400	멱등키 형식이 올바르지 않습니다.	Invalid idempotency key format.	Idempotency-Key 헤더에 UUID v4 형식의 값을 사용하세요.
COMMON_IDEMPOTENCY_KEY_IN_PROGRESS	409	동일한 멱등키 요청이 처리 중입니다.	Request with the same idempotency key is in progress.	이전 요청 처리가 완료될 때까지 기다린 후 재시도하세요.
COMMON_IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST	409	동일한 멱등키로 다른 요청 본문을 사용할 수 없습니다.	The same idempotency key cannot be reused with a different request.	새 요청에는 새 멱등키를 생성하세요.
CREDIT_INSUFFICIENT_BALANCE	402	크레딧 잔액이 부족합니다.	Insufficient credit balance.	콘솔에서 크레딧 잔액을 확인하고 충전하세요.
USAGE_DAILY_LIMIT_EXCEEDED	429	일일 사용 한도를 초과했습니다.	Daily usage limit exceeded.	콘솔에서 일일 사용 한도를 확인하세요. 한도 상향이 필요하면 관리자에게 문의하세요.
USAGE_MONTHLY_LIMIT_EXCEEDED	429	월간 사용 한도를 초과했습니다.	Monthly usage limit exceeded.	콘솔에서 월간 사용 한도를 확인하세요. 한도 상향이 필요하면 관리자에게 문의하세요.
COUPON_INVALID_COUPON_ID	400	쿠폰 ID 형식이 올바르지 않습니다.	Invalid coupon ID format.	couponId는 cpn_ 접두사로 시작하는 ULID 형식이어야 합니다.
COUPON_NOT_FOUND	404	쿠폰을 찾을 수 없습니다.	Coupon not found.	couponId가 정확한지, 해당 쿠폰이 고객사에 할당되었는지 확인하세요.
COUPON_PIN_NOT_ISSUABLE	400	해당 쿠폰은 PIN 발급을 지원하지 않습니다.	This coupon does not support PIN issuance.	카탈로그 API에서 capabilities에 "PIN"이 포함된 쿠폰만 PIN 발급이 가능합니다.
COUPON_PIN_ORDER_ID_CONFLICT	409	이미 사용된 orderId입니다.	The orderId is already used.	다른 orderId를 사용하거나, 기존 발급 결과를 상태 조회 API로 확인하세요.
COUPON_PIN_VENDOR_ISSUE_FAILED	502	PIN 발급에 실패했습니다.	PIN issuance failed.	벤더 측 일시적 오류일 수 있습니다. 잠시 후 재시도하세요.

발급 조회

GET /v1/coupons/issued

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COUPON_INVALID_ISSUANCE_ID	400	발급 ID 형식이 올바르지 않습니다.	Invalid issuance ID format.	id는 iss_ 접두사로 시작하는 형식이어야 합니다.
COUPON_ISSUANCE_NOT_FOUND	404	발급 내역을 찾을 수 없습니다.	Issuance not found.	id 또는 orderId가 정확한지 확인하세요.

발급 취소

POST /v1/coupons/issued/cancel

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COUPON_INVALID_ISSUANCE_ID	400	발급 ID 형식이 올바르지 않습니다.	Invalid issuance ID format.	id는 iss_ 접두사로 시작하는 형식이어야 합니다.
COUPON_ISSUANCE_NOT_FOUND	404	발급 내역을 찾을 수 없습니다.	Issuance not found.	id 또는 orderId가 정확한지 확인하세요.
COUPON_ALREADY_CANCELED	409	이미 취소된 쿠폰입니다.	This coupon has already been canceled.	해당 쿠폰은 이미 취소 처리되었습니다. 조회 API로 현재 상태를 확인하세요.
COUPON_NOT_CANCELABLE	409	취소할 수 없는 상태입니다.	The coupon is not in a cancelable state.	ISSUED 상태인 쿠폰만 취소할 수 있습니다. 조회 API로 현재 상태를 확인하세요.
COUPON_CANCEL_VENDOR_FAILED	502	쿠폰 취소에 실패했습니다.	Coupon cancellation failed.	벤더 측 일시적 오류일 수 있습니다. 잠시 후 재시도하세요.

메시지 재발송

POST /v1/coupons/issued/resend

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
COUPON_INVALID_ISSUANCE_ID	400	발급 ID 형식이 올바르지 않습니다.	Invalid issuance ID format.	id는 iss_ 접두사로 시작하는 형식이어야 합니다.
COUPON_ISSUANCE_NOT_FOUND	404	발급 내역을 찾을 수 없습니다.	Issuance not found.	id 또는 orderId가 정확한지 확인하세요.
COUPON_RESEND_NOT_ALLOWED	409	재발송할 수 없는 상태입니다.	Resending is not allowed in the current state.	발송 실패 또는 발급 완료 상태인 경우에만 재발송할 수 있습니다.
COUPON_RESEND_VENDOR_FAILED	502	재발송에 실패했습니다.	Resending failed.	벤더 측 일시적 오류일 수 있습니다. 잠시 후 재시도하세요.

발급 이미지 조회

GET /v1/coupons/issued/image

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
AUTH_INVALID_PRESIGNED_URL	401	유효하지 않거나 만료된 URL입니다.	Invalid or expired pre-signed URL.	Pre-signed URL이 만료되었을 수 있습니다. 발급 조회 API를 다시 호출하여 새 imageUrl을 받으세요.
COUPON_INVALID_ISSUANCE_ID	400	발급 ID 형식이 올바르지 않습니다.	Invalid issuance ID format.	id는 iss_ 접두사로 시작하는 형식이어야 합니다.
COUPON_ISSUANCE_NOT_FOUND	404	발급 내역을 찾을 수 없습니다.	Issuance not found.	id 또는 orderId가 정확한지 확인하세요.
COUPON_IMAGE_NOT_READY	404	이미지가 아직 생성되지 않았습니다.	Image is not ready yet.	발급 직후에는 이미지 생성에 수 초가 소요됩니다. 잠시 후 다시 요청하세요.
COUPON_IMAGE_NOT_SUPPORTED	400	이미지를 지원하지 않는 쿠폰입니다.	This coupon does not support image.	해당 쿠폰은 이미지 조회를 지원하지 않습니다.

잔액 조회

GET /v1/account/balance

코드	HTTP	메시지 (한국어)	메시지 (English)	해결 방법
CREDIT_ACCOUNT_NOT_FOUND	402	크레딧 계정이 활성화되지 않았습니다.	Credit account is not activated.	콘솔에서 크레딧 계정을 활성화하세요.

사용량 조회

GET /v1/account/usage

이 엔드포인트에는 전용 에러 코드가 없습니다. 공통 에러를 참고하세요.

사용량 한도 설정

PUT /v1/account/usage/limits

이 엔드포인트에는 전용 에러 코드가 없습니다. 공통 에러를 참고하세요.

---

HTTP 상태 코드 요약

상태 코드	의미	대응 방법
400	잘못된 요청	요청 파라미터를 확인하세요
401	인증 실패	API 키가 올바른지 확인하세요
402	크레딧 부족	콘솔에서 크레딧을 충전하세요
403	접근 거부	HTTPS를 사용하고 있는지 확인하세요
404	리소스 없음	요청한 리소스 ID를 확인하세요
409	충돌	orderId 중복 또는 멱등키 관련 에러를 확인하세요
429	요청/사용 한도 초과	Rate Limit이면 잠시 후 재시도, 사용량 한도이면 콘솔에서 한도를 확인하세요
500	서버 내부 오류	잠시 후 재시도하세요. 지속 시 문의하세요
502	벤더 오류	일시적 오류일 수 있습니다. 잠시 후 재시도하세요

재시도 가이드

• 4xx 에러: 요청을 수정한 후 재시도하세요. 동일한 요청을 반복해도 같은 에러가 발생합니다.
• 429 에러: 지수 백오프(exponential backoff)로 재시도하세요.
• 5xx 에러: 일시적 오류일 수 있으므로 잠시 후 재시도하세요. 지속되면 담당자에게 문의하세요.