请求限制

了解和管理TCG Price Lookup API的请求限制、每日配额和突发速率。

各计划请求限制

计划每日请求数突发速率
免费200每3秒1次请求
Trader10,000每秒1次请求
Business100,000每秒3次请求

每日限制在UTC午夜重置。

请求限制响应头

所有API响应都包含当前请求限制信息：

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 150
X-RateLimit-Reset: 1704067200
响应头说明
X-RateLimit-Limit该周期内的最大请求数
X-RateLimit-Remaining剩余请求数
X-RateLimit-Reset限制重置的Unix时间戳

处理429错误

超出请求限制时，将返回429 Too Many Requests：

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

使用Retry-After响应头确定下次请求前需等待的时间：

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;
  }
}

最佳实践

使用批量请求（需要Trader计划或更高级别）：

// 低效：20次单独请求
for (const id of cardIds) {
  await tcg.cards.get(id); // ✗
}

// 高效：1次批量请求
const cards = await tcg.cards.batch(cardIds); // ✓

缓存响应：

价格数据每隔数小时更新一次。对大多数使用场景来说，短期缓存（5-15分钟）是合理的选择：

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5分钟

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;
}