Rate limits & quotas

Việc sử dụng API bị giới hạn bởi rate limit theo phút và quota hằng ngày theo kênh (billable units). Giới hạn được đặt trong quá trình onboarding app dựa trên khối lượng giao dịch dự kiến — xem Acceptable use.

Giới hạn và header có cấu trúc: data/rate-limits.json.

Rate limit theo phút {#rate-limits}

Mặc định: 60 request/phút cho mỗi API key (tùy plan). Vượt quá → HTTP 429 với RATE_LIMIT_EXCEEDED.

Quota kênh hằng ngày (billable units) {#daily-quota}

Nhiều route tiêu thụ billable units theo giới hạn hằng ngày cho mỗi kênh (1688, Taobao). Ví dụ:

Route	Đơn vị thường dùng
POST /v1/products/detail	1
POST /v1/products/search	2
POST /v1/products/upload-image	2
POST /v1/orders/preview, create	Trọng số cao hơn — xem plan

Khi hết quota hằng ngày → HTTP 429 với QUOTA_EXCEEDED. Liên hệ HIOBuy để tăng giới hạn khi GMV của bạn tăng.

Header phản hồi {#response-headers}

Các cuộc gọi tính phí thành công có thể bao gồm:

Header	Mô tả
X-Quota-Billable-Units	Số đơn vị request này đã tiêu thụ
X-Quota-Channel	Kênh bị tính đơn vị (ví dụ 1688)
x-request-id	Id tương quan request (mọi route)

Năng lực nền tảng {#platform-quota}

Hiếm khi, năng lực upstream dùng chung có thể tạm thời không khả dụng → PLATFORM_QUOTA_EXCEEDED (429). Retry sau hoặc liên hệ support.

Khuyến nghị cho client {#handling}

• Cache response chi tiết sản phẩm khi quy tắc nghiệp vụ cho phép.
• Ưu tiên tái sử dụng image_id sau upload-image thay vì upload lại.
• Back off khi gặp 429; đọc error.request_id — xem Errors.
• Theo dõi usage trong dashboard usage của developer portal.