Rate limits & quotas
API usage is limited by per-minute rate limits and per-channel daily quotas (billable units). Limits are set during app onboarding based on expected transaction volume — see Acceptable use.
Structured limits and headers: data/rate-limits.json.
Per-minute rate limit {#rate-limits}
Default: 60 requests/minute per API key (subject to plan). Exceeded → HTTP 429 with RATE_LIMIT_EXCEEDED.
Daily channel quota (billable units) {#daily-quota}
Many routes consume billable units against a daily cap per channel (1688, Taobao). Examples:
| Route | Typical units |
|---|---|
POST /v1/products/detail | 1 |
POST /v1/products/search | 2 |
POST /v1/products/upload-image | 2 |
POST /v1/orders/preview, create | Higher weight — see plan |
When the daily cap is exhausted → HTTP 429 with QUOTA_EXCEEDED. Contact HIOBuy to raise limits as your GMV grows.
Response headers {#response-headers}
Successful billable calls may include:
| Header | Description |
|---|---|
X-Quota-Billable-Units | Units consumed by this request |
X-Quota-Channel | Channel the units were charged against (e.g. 1688) |
x-request-id | Request correlation id (all routes) |
Platform capacity {#platform-quota}
Rarely, shared upstream capacity may be temporarily unavailable → PLATFORM_QUOTA_EXCEEDED (429). Retry later or contact support.
Client recommendations {#handling}
- Cache product detail responses where business rules allow.
- Prefer
image_idreuse afterupload-imageinstead of re-uploading. - Back off on
429; readerror.request_id— see Errors. - Monitor usage in the developer portal usage dashboard.