المفاهيم

حدود المعدّل والحصص

تحافظ الحدود على سرعة Linework وخلوّها من الرسائل المزعجة. إنها سخية مع التكاملات الحقيقية وصارمة مع إساءة الاستخدام.

الطلبات في الدقيقة#

يمكن لكل مفتاح API إرسال 120 طلبًا في الدقيقة. تحمل كل استجابة هذه الترويسات:

عند تجاوز الحد تتلقى 429 مع الرمز RATE_LIMITED والترويسة Retry-After (عدد الثواني التي يجب انتظارها):

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry later" } }

الحصص اليومية#

تُحتسب إجراءات الكتابة أيضًا ضمن حصص يومية لكل حساب، مجموعةً عبر كل مفاتيحه. يُعاد ضبط الحصص عند منتصف الليل بتوقيت UTC.

عند استنفاد حصة ما، يفشل هذا النوع من الإجراءات مع 429 حتى اليوم التالي بتوقيت UTC، وتستمر نقاط النهاية الأخرى في العمل. لا توجد حصة يومية لنقاط نهاية المتجر والطلبات، بل الحد في الدقيقة فقط.

قاعدة مكافحة الرسائل المزعجة في الدردشة#

لا يمكن للروبوت مراسلة إلا الأشخاص الذين يرغبون في التواصل معه. يُسمح بالرسالة عندما يتحقق واحد على الأقل مما يلي:

• أن يكون الطرف الآخر قد كتب بالفعل في تلك المحادثة، أو
• أن يكون الطرف الآخر يتابع حسابك.

وإلا يفشل الطلب مع 403 CHAT_NOT_ALLOWED. وإذا حظر أحدكما الآخر، يفشل مع 403 CHAT_BLOCKED.

الخصوصية والحظر#

تتبع الواجهة القواعد نفسها التي يتبعها التطبيق: يبقى المستخدمون المحظورون والملفات الشخصية الخاصة بعيدين عن الوصول. الملف الشخصي الخاص الذي لا تتابع صاحبه، أو المستخدم الذي حظرك، يُعامَل كأنه غير موجود أو غير مسموح به — لا تُعِد محاولة هذه الطلبات في حلقة متكررة أبدًا.

التعامل الجيد مع 429#

• اقرأ Retry-After وانتظر تلك المدة على الأقل قبل إعادة المحاولة.
• استخدم التراجع الأُسّي (exponential backoff) مع قدر من التأخير العشوائي (jitter) عند تكرار الإخفاقات.
• راقب X-RateLimit-Remaining وأبطئ قبل الوصول إلى الصفر.
• فضّل طلبًا واحدًا مرقّم الصفحات مع limit=100 على كثير من الطلبات الصغيرة.

async function call(url, options = {}, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, {
      ...options,
      headers: { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`, ...options.headers },
    });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") || 2 ** i);
    await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000));
  }
  throw new Error("Still rate limited");
}

import os, random, time, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

def call(method, path, tries=5, **kw):
    for i in range(tries):
        r = s.request(method, API + path, timeout=30, **kw)
        if r.status_code != 429:
            return r
        wait = float(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait + random.random())
    raise RuntimeError("Still rate limited")