에러

API는 표준 HTTP 상태 코드를 사용하며, 에러 응답은 하나의 JSON 형식을 공유합니다.

에러 응답 바디

{
  "errorCode": "account_balance_insufficient",
  "message": "Account balance is insufficient"
}

📘
한 가지 예외: 401 Unauthorized는 빈 바디를 반환합니다 (JSON 없음). 401은 모두 API 키 누락/오류로 처리하세요.

HTTP	`errorCode`	의미 / 대처
400	`invalid_request`	필드 누락·형식 오류·검증 실패 (범용). `message`에 해당 필드가 표시됩니다.
400	`invalid_phone_number_format`	`recipient.phone_number`가 상품 국가의 형식과 맞지 않습니다.
401	(빈 바디)	API 키 누락·오류, 또는 키/환경 불일치.
403	`permission_denied`	이 작업을 수행할 권한이 없는 키입니다.
404	`not_found`	존재하지 않는 경로 또는 리소스.
405	`method_not_allowed`	잘못된 HTTP 메서드.
429	`rate_limit_exceeded`	요청 과다 — 요청 제한 참고.
500	`unhandled_error`	예기치 못한 서버 오류. 지속되면 문의하세요.

HTTP	`errorCode`	의미 / 대처
400	`account_balance_insufficient`	잔액 부족. 대시보드에서 충전하세요 (충전).
400	`price_range_exceed`	`custom_amount`가 상품의 `min_amount`–`max_amount` 범위를 벗어남. 참고: `1` 미만 값은 스키마 검증에 먼저 걸려 `invalid_request`가 반환됩니다.
400	`invalid_order_access`	주문이 존재하지만 내 계정 소유가 아닙니다.
400	`resend_not_allowed`	재발송은 `EMAIL`·`TEXT` 주문 아이템만 지원합니다.
400	`acceptance_expired`	수신자의 수락 링크가 만료됐습니다.
400	`order_item_cancelled`	취소된 주문 아이템에는 작업할 수 없습니다.
404	`order_not_found` / `order_item_not_found`	내 계정에 해당 주문/주문 아이템이 없습니다.
404	`order_item_not_issued`	바우처가 아직 발급되지 않음 — 아이템 완료 후 다시 시도하세요.
500	`order_retry_needed`	일시적 동시성 충돌. 재시도해도 안전 — `external_reference_id`를 쓰면 재시도해도 중복 주문이 생기지 않습니다.

HTTP	`errorCode`	의미 / 대처
404	`item_not_found`	존재하지 않는 상품 ID.

재시도: 429 (1초 후), order_retry_needed가 담긴 500 (짧은 백오프로 몇 회).
재시도 금지: 그 외 모든 400 — 요청을 먼저 고치세요.
주문 생성 시 항상 external_reference_id를 전달해 재시도가 절대 중복 주문을 만들지 않게 하세요. 중복 방지와 재시도 참고.