概念

速率限制与配额

限制让 Linework 保持快速且远离垃圾信息。对真实的集成而言限制很宽松，对滥用行为则很严格。

每分钟请求数#

每个 API 密钥每分钟可发出 120 个请求。每个响应都带有以下请求头：

请求头	含义
`X-RateLimit-Limit`	当前时间窗口内允许的请求数（120）。
`X-RateLimit-Remaining`	当前时间窗口内剩余的请求数。
`X-RateLimit-Reset`	时间窗口重置的时间（确切格式请参阅 API 参考）。

超出限制时，您会收到 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 午夜重置。

操作	每日上限
帖子	50
评论	300
点赞	500
关注	100
快拍	20
聊天消息	500

某项配额用完后，该类操作会返回 429，直到下一个 UTC 日；其他端点仍可正常使用。店铺和订单端点没有每日配额，只有每分钟限制。

聊天反垃圾消息规则#

机器人只能给愿意接收其消息的人发消息。当满足以下至少一项条件时，才允许发送消息：

对方已经在该会话中发过消息，或
对方关注了您的账号。

否则请求会返回 403 CHAT_NOT_ALLOWED。如果你们中有一方屏蔽了另一方，则返回 403 CHAT_BLOCKED。

隐私与屏蔽#

API 遵循与应用相同的规则：被屏蔽的用户和私密资料无法访问。对于您未关注的私密资料，或屏蔽了您的用户，其表现与“未找到”或“不允许”相同 — 切勿循环重试这类请求。

妥善处理 429#

读取 Retry-After，并在重试前至少等待相应时长。
对于反复失败的情况，请使用带随机抖动的指数退避。
关注 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")

出于正当用途需要更高的限制？请发送邮件至 developers@linework.app，说明您正在构建的内容。