Giới hạn tốc độ

Hiểu và quản lý giới hạn tốc độ, hạn mức ngày và tốc độ burst của TCG Price Lookup API.

Giới hạn tốc độ theo gói

Giới hạn ngày đặt lại mỗi ngày vào lúc nửa đêm UTC.

Header giới hạn tốc độ

Tất cả response API bao gồm thông tin giới hạn tốc độ hiện tại:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 150
X-RateLimit-Reset: 1704067200

Xử lý lỗi 429

Khi vượt quá giới hạn tốc độ, bạn nhận được 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily request limit reached. Resets at midnight UTC."
  }
}

Sử dụng header Retry-After để biết thời gian đợi trước yêu cầu tiếp theo:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('retry-after') || '60');
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
}

Thực hành tốt nhất

Sử dụng yêu cầu hàng loạt (Gói Trader trở lên):

// Kém hiệu quả: 20 yêu cầu riêng lẻ
for (const id of cardIds) {
  await tcg.cards.get(id); // ✗
}

// Hiệu quả: 1 yêu cầu hàng loạt
const cards = await tcg.cards.batch(cardIds); // ✓

Cache response:

Giá được cập nhật vài giờ một lần. Cache ngắn hạn (5–15 phút) phù hợp với nhiều trường hợp sử dụng:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 phút

async function getCachedCard(id) {
  const cached = cache.get(id);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  const data = await tcg.cards.get(id);
  cache.set(id, { data, timestamp: Date.now() });
  return data;
}