حدود المعدّل

تطبّق واجهة API العامة حصة طلبات متجدّدة مدتها دقيقة واحدة على كل مفتاح API أو رمز وصول OAuth. إنشاء مفاتيح إضافية للالتفاف على أحد الحدود غير مدعوم، وقد يؤدي إلى فرض قيود على بيانات الاعتماد أو الحساب.

حدود الخطط#

تتلقى بيانات الاعتماد التي لا يملك حسابها خطة مدفوعة نشطة الاستجابة 403 subscription_required قبل منحها أي سعة ضمن حدود المعدّل. يمكن لـ Make Agent Fast تطبيق حدود أدنى خاصة ببعض نقاط النهاية للعمليات المكلفة بشكل غير معتاد، وعند حدوث ذلك سيوضّح مرجع نقطة النهاية هذه الحدود صراحةً.

استجابة تجاوز حد المعدّل#

عند استنفاد الحصة، تعيد API الاستجابة 429 rate_limit_exceeded مع:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json

تمثّل Retry-After الحد الأدنى لعدد الثواني التي يجب انتظارها. كما تتضمن كل استجابة موثّقة الترويسات X-RateLimit-Limit وX-RateLimit-Remaining و X-RateLimit-Reset (طابع زمني بنظام Unix)، بحيث تستطيع التطبيقات تنظيم معدّل طلباتها قبل الوصول إلى 429.

تنفيذ إعادة المحاولة#

استخدم التراجع الأسّي مع تباين عشوائي (jitter)، والتزم بقيمة Retry-After إذا كانت أكبر، وحدّد سقفًا لإجمالي عدد المحاولات.

async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}

في طلبات POST وPATCH وDELETE، احتفظ بالقيمة الصالحة نفسها للترويسة Idempotency-Key عبر كل عمليات إعادة المحاولة الناتجة عن أخطاء الشبكة أو الخادم. قد يؤدي مفتاح idempotency جديد إلى تكرار أثر جانبي اكتمل بالفعل.

تقليل حجم الطلبات#

• خزّن مؤقتًا عمليات قراءة الحساب والموقع والإعدادات التي لا تتطلب بيانات محدّثة في الوقت الفعلي.
• اطلب ما يصل إلى 100 سجل في الصفحة بدلًا من طلب صفحات صغيرة جدًا بشكل متكرر.
• عالج أحداث webhook بدلًا من الاستعلام الدوري عن المحادثات أو العملاء المحتملين (Leads) أو رسائل البث.
• حدّد عدد العمليات المتزامنة للعمال (workers) لكل مفتاح API؛ فالدفعات المفاجئة من عدد كبير من استدعاءات serverless تتشارك الحصة نفسها.
• استخدم مفاتيح منفصلة للخدمات المنفصلة لأغراض العزل وسهولة التدقيق، وليس لمضاعفة سعة عبء عمل واحد.

جدول ما يُعاد وما لا يُعاد#

إذا تجاوز عبء عمل مستمر حصة خطتك بشكل مشروع، فقلّل الاستعلام الدوري، أو جمّع العمليات في دفعات، أو تواصل مع الدعم مع معرّفات طلبات تمثيلية وحجم الزيارات المتوقع، بدلًا من إضافة حلقة إعادة محاولة بلا حدود.