कॉन्सेप्ट्स

Rate limits और quotas

ये सीमाएँ Linework को तेज़ और स्पैम-मुक्त रखती हैं। असली integrations के लिए ये उदार हैं और दुरुपयोग के लिए सख़्त।

प्रति मिनट requests#

हर API key प्रति मिनट 120 requests कर सकती है। हर response में ये headers होते हैं:

सीमा पार होने पर आपको RATE_LIMITED code के साथ 429 मिलता है, और एक Retry-After header (इंतज़ार करने के सेकंड):

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" } }

दैनिक quotas#

Write actions दैनिक quotas में भी गिने जाते हैं, जो हर अकाउंट के लिए उसकी सभी keys को मिलाकर होते हैं। Quotas UTC आधी रात को reset होते हैं।

जब कोई quota ख़त्म हो जाता है, तो उस तरह का action अगले UTC दिन तक 429 के साथ fail होता है; बाकी endpoints काम करते रहते हैं। स्टोर और ऑर्डर endpoints का कोई दैनिक quota नहीं है, सिर्फ़ प्रति मिनट की सीमा है।

चैट का anti-spam नियम#

एक bot सिर्फ़ उन्हीं लोगों को मैसेज भेज सकता है जो उससे सुनना चाहते हैं। मैसेज तब अनुमत है जब इनमें से कम से कम एक बात सच हो:

• दूसरे व्यक्ति ने उस बातचीत में पहले ही लिखा है, या
• दूसरा व्यक्ति आपके अकाउंट को फ़ॉलो करता है।

वरना request 403 CHAT_NOT_ALLOWED के साथ fail होती है। अगर आप में से किसी ने दूसरे को ब्लॉक किया है, तो यह 403 CHAT_BLOCKED के साथ fail होती है।

Privacy और ब्लॉक#

API वही नियम मानता है जो ऐप मानता है: ब्लॉक किए गए यूज़र्स और प्राइवेट प्रोफ़ाइल पहुँच से बाहर रहते हैं। ऐसी प्राइवेट प्रोफ़ाइल जिसके मालिक को आप फ़ॉलो नहीं करते, या ऐसा यूज़र जिसने आपको ब्लॉक किया है, “नहीं मिला” या “अनुमति नहीं” की तरह व्यवहार करता है — ऐसी requests को कभी loop में retry न करें।

429 को सही तरह हैंडल करना#

• Retry-After पढ़ें और retry करने से पहले कम से कम उतनी देर इंतज़ार करें।
• बार-बार fail होने पर थोड़े random jitter के साथ exponential backoff इस्तेमाल करें।
• X-RateLimit-Remaining पर नज़र रखें और शून्य तक पहुँचने से पहले रफ़्तार कम करें।
• कई छोटी requests के बजाय limit=100 वाली एक paginated request को प्राथमिकता दें।

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")