حدود المعدل

فهم وإدارة حدود معدل الطلبات والحصص اليومية ومعدلات الانفجار في TCG Price Lookup API.

حدود المعدل حسب الخطة

تُعاد تهيئة الحدود اليومية كل يوم عند منتصف الليل UTC.

رؤوس حد المعدل

تتضمن جميع استجابات API معلومات حد المعدل الحالية:

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

التعامل مع خطأ 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); // ✗
}

// فعّال: طلب مجمّع واحد
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;
}