Skip to content

Rate Limit & Hạn Mức Quota ​

Hệ thống quản lý lưu lượng và hạn mức thông qua 2 cơ chế độc lập: Rate Limit (giới hạn tốc độ theo phút) và Quota (hạn mức tổng theo tháng / ngày).


1. Giới Hạn Tốc Độ (Rate Limit - RPM) ​

  • Ý nghĩa: Số lượt request tối đa mà 1 API Key được phép gửi trong vòng 1 phút (ví dụ: 60 rpm tương đương 1 req/giây).
  • Cơ chế: Cửa sổ trượt 60 giây (Sliding Window).

Khi vượt quá Rate Limit ​

Hệ thống trả về HTTP 429 Too Many Requests:

http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 18s."
  },
  "data": null
}

TIP

Xử lý với Header Retry-After: Khi nhận mã lỗi 429 RATE_LIMITED, hệ thống luôn gửi kèm header Retry-After chứa số giây cần chờ. Ứng dụng của bạn nên đọc giá trị này để delay thử lại thay vì gửi dồn dập.


2. Hạn Mức Quota ​

  • Hạn mức chu kỳ: Mỗi key được cấp một hạn mức tìm kiếm (ví dụ: 10,000 lượt hoặc 30,000 lượt / chu kỳ).
  • Múi giờ làm mới: Múi giờ chuẩn Việt Nam Asia/Ho_Chi_Minh (GMT+7).
  • Cộng dồn đa nền tảng: Quota được tính chung trên các request đã chuyển tới upstream Shopee, TikTok và Douyin của key đó (các request lỗi xác thực 401/403 hoặc gọi /v1/me, /v1/health không bị trừ quota).

Khi hết Quota ​

Hệ thống trả về HTTP 429 Too Many Requests:

http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded. Resets on the 1st of next month (Asia/Ho_Chi_Minh)."
  },
  "data": null
}

3. Các Response Headers Giám Sát Lưu Lượng ​

Mỗi request hợp lệ khi gửi qua ImageCoreAPI đều được trả về các Header đo lường lưu lượng theo thời gian thực:

HeaderÝ nghĩaVí dụ
X-RateLimit-LimitGiới hạn RPM cấu hình cho key60
X-RateLimit-RemainingSố lượt còn lại trong cửa sổ phút hiện tại48
X-RateLimit-ResetSố giây còn lại đến khi reset cửa sổ phút15
X-Quota-Monthly-LimitTổng hạn mức tháng được cấp30000
X-Quota-Monthly-RemainingSố lượt tìm kiếm còn lại trong chu kỳ24150

4. Khuyến Nghị Xử Lý Retry Tự Động (Exponential Backoff) ​

Dưới đây là đoạn mã mẫu triển khai retry an toàn trong ứng dụng của bạn:

python
import time
import httpx

def search_with_retry(url, headers, payload, max_retries=3):
    for attempt in range(max_retries):
        response = httpx.post(url, headers=headers, json=payload, timeout=60.0)
        
        # Nếu bị Rate Limit, đọc header Retry-After và chờ
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 5))
            print(f"Bị giới hạn tốc độ. Chờ {retry_after}s trước khi thử lại (lần {attempt + 1})...")
            time.sleep(retry_after)
            continue
            
        return response
        
    raise Exception("Vượt quá số lần thử lại tối đa.")
javascript
async function searchWithRetry(url, headers, payload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload)
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "5", 10);
      console.warn(`Bị rate limit. Chờ ${retryAfter}s trước khi thử lại...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error("Vượt quá số lần thử lại tối đa.");
}

ImageCoreAPI — Cổng API tìm kiếm hình ảnh Shopee & TikTok Shop