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/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 tổng số request thành công tới cả Shopee và TikTok 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/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ĩa	Ví dụ
X-RateLimit-Limit	Giới hạn RPM cấu hình cho key	60
X-RateLimit-Remaining	Số lượt còn lại trong cửa sổ phút hiện tại	48
X-RateLimit-Reset	Số giây còn lại đến khi reset cửa sổ phút	15
X-Quota-Monthly-Limit	Tổng hạn mức tháng được cấp	30000
X-Quota-Monthly-Remaining	Số 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 / Node.js

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.");
}