حدود المعدل

تطبّق واجهة TakeTheme البرمجية حدودًا للمعدل لضمان الاستخدام العادل والحفاظ على استقرار الخدمة. والحد الافتراضي هو 140 طلبًا لكل نافذة منزلقة مدتها 60 ثانية، وتطبّق بعض مجموعات العناوين (مثل التحليلات) حدودًا أكثر صرامة خاصة بكل متجر. ولا تُحتسب الطلبات المرفوضة ضمن نافذتك، فلا تستطيع حلقة إعادة المحاولة إطالة حظرها بنفسها. وإذا احتجت حدودًا مخصصة، راسل support@taketheme.com.

ترويسات حدود المعدل

تتضمن الاستجابات الخاضعة لحدود المعدل هذه الترويسات:

HTTP/1.1 200 OK
X-RateLimit-Limit: 140
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 24

الترويسة	الوصف
X-RateLimit-Limit	أقصى عدد طلبات مسموح في النافذة
X-RateLimit-Remaining	الطلبات المتبقية في النافذة الحالية
X-RateLimit-Reset	الثواني المتبقية حتى تتحرّر السعة (وليست طابعًا زمنيًا)

حصص استخدام مفاتيح الـ API

بمعزل عن حد المعدل لكل نافذة، يمكن إنشاء مفتاح API بـحصة استخدام إجمالية. وتُبلّغ الاستجابات على الطلبات المُصادَقة بمفتاح عن حالة الحصة في مجموعة الترويسات نفسها، مع معرّف للسلة:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99312
X-RateLimit-Reset: 0
X-RateLimit-Bucket: 665f2a...

هنا يعكس Limit وRemaining حصة المفتاح مدى عمره (والقيمة Reset: 0 تعني عدم وجود تصفير زمني)، وX-RateLimit-Bucket هو معرّف مفتاح الـ API. وعند نفاد الحصة تُعيد الواجهة الخطأ 429 API_KEY_USAGE_LIMIT_REACHED.

تجاوز حد المعدل

عند تجاوزك حد المعدل، تُعيد الواجهة الاستجابة 429 Too Many Requests:

{
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "status": 429
}

وتتضمن الاستجابة ترويسة Retry-After تبيّن عدد الثواني التي يجب انتظارها قبل إعادة المحاولة:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 140
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45

التعامل مع حدود المعدل

التراجع الأُسّي

طبّق تراجعًا أُسّيًا لإعادة المحاولة التلقائية:

async function fetchWithBackoff(url, options, maxRetries = 5) {
  let delay = 1000; // Start with 1 second

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After");
      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : delay;

      console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
      await new Promise((resolve) => setTimeout(resolve, waitTime));

      delay *= 2; // Double the delay for next attempt
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}

تنفيذ بلغة Python

import time
import requests
from functools import wraps

def retry_with_backoff(max_retries=5, base_delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            delay = base_delay
            for attempt in range(max_retries):
                response = func(*args, **kwargs)

                if response.status_code == 429:
                    retry_after = int(response.headers.get('Retry-After', delay))
                    print(f"Rate limited. Waiting {retry_after}s...")
                    time.sleep(retry_after)
                    delay *= 2
                    continue

                return response

            raise Exception("Max retries exceeded")
        return wrapper
    return decorator

@retry_with_backoff(max_retries=5)
def get_products(api_key):
    return requests.get(
        'https://api.taketheme.com/api/v1/product',
        headers={'tt-api-key': f'{api_key}'}
    )

الحد الاستباقي من المعدل

راقب الطلبات المتبقية وخفّف الوتيرة قبل بلوغ الحدود:

class RateLimitedClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.remaining = Infinity;
    this.resetTime = 0;
  }

  async request(endpoint, options = {}) {
    // Wait if we're close to the limit
    if (this.remaining < 5) {
      const waitTime = (this.resetTime - Date.now() / 1000) * 1000;
      if (waitTime > 0) {
        console.log(`Approaching rate limit. Waiting ${waitTime}ms...`);
        await new Promise((resolve) => setTimeout(resolve, waitTime));
      }
    }

    const response = await fetch(`https://api.taketheme.com/api/v1${endpoint}`, {
      ...options,
      headers: {
        "tt-api-key": this.apiKey,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    // Update rate limit tracking (Reset is seconds until capacity frees)
    this.remaining = parseInt(
      response.headers.get("X-RateLimit-Remaining") || "0"
    );
    const resetSeconds = parseInt(response.headers.get("X-RateLimit-Reset") || "0");
    this.resetTime = Date.now() / 1000 + resetSeconds;

    return response;
  }
}

طلب حدود أعلى

إذا احتجت حدود معدل أعلى:

1. رقِّ باقتك — تتضمن الباقات الأعلى حدودًا أكبر
2. تواصل مع المبيعات — للمتطلبات على مستوى المؤسسات، راسل sales@taketheme.com
3. حسّن تكاملك — كثيرًا ما تُغني التغييرات المعمارية عن الحاجة إلى حدود أعلى

اقرأ أيضًا

• التقسيم إلى صفحات — جلب مجموعات البيانات الكبيرة بكفاءة
• معالجة الأخطاء — التعامل مع كل أخطاء الـ API بسلاسة
• الويب هوك — تقليل الاستعلام المتكرر بالأحداث اللحظية