Rate Limit

TCG Price Lookup API의 rate limit, 일일 할당량, 버스트 rate의 이해 및 관리 방법.

플랜별 Rate Limit

일일 제한은 매일 UTC 자정에 초기화됩니다.

Rate Limit 헤더

모든 API 응답에 현재 rate limit 정보가 포함됩니다:

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

429 에러 처리

Rate limit을 초과하면 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;
}