속도 제한 및 쿼터

API 사용량은 분당 속도 제한과 채널별 일일 쿼터(과금 단위)로 제한됩니다. 한도는 예상 거래량을 기준으로 앱 온보딩 중 설정됩니다 — Acceptable use를 참고하세요.

구조화된 제한과 헤더: data/rate-limits.json.

분당 속도 제한 {#rate-limits}

기본값: API 키당 60 requests/minute(플랜에 따라 다름). 초과 시 HTTP 429와 RATE_LIMIT_EXCEEDED가 반환됩니다.

일일 채널 쿼터(과금 단위) {#daily-quota}

많은 라우트는 채널별(1688, Taobao) 일일 한도에서 billable units를 소비합니다. 예시:

라우트	일반적인 단위
POST /v1/products/detail	1
POST /v1/products/search	2
POST /v1/products/upload-image	2
POST /v1/orders/preview, create	더 높은 가중치 — 플랜 참고

일일 한도가 소진되면 HTTP 429와 QUOTA_EXCEEDED가 반환됩니다. GMV가 증가하면 HIOBuy에 문의해 한도를 올리세요.

응답 헤더 {#response-headers}

성공한 과금 대상 호출에는 다음이 포함될 수 있습니다.

헤더	설명
X-Quota-Billable-Units	이 요청이 소비한 단위
X-Quota-Channel	단위가 차감된 채널(예: 1688)
x-request-id	요청 상관 id(모든 라우트)

플랫폼 용량 {#platform-quota}

드물게 공유 upstream 용량을 일시적으로 사용할 수 없을 수 있습니다 → PLATFORM_QUOTA_EXCEEDED(429). 나중에 재시도하거나 지원팀에 문의하세요.

클라이언트 권장 사항 {#handling}

• 비즈니스 규칙이 허용하는 경우 상품 상세 응답을 캐시하세요.
• upload-image 후 다시 업로드하는 대신 image_id 재사용을 선호하세요.
• 429에서는 백오프하고 error.request_id를 읽으세요 — Errors 참고.
• 개발자 포털의 사용량 대시보드에서 사용량을 모니터링하세요.