速率限制

Shoplazza API 速率限制

所有 Shoplazza API 都有速率限制。REST Admin API 使用基于请求数的限制：每个请求计数相同，与返回的数据量无关。

REST Admin API 基于两个维度执行速率限制：

• 应用/店铺：每个应用和店铺组合都有独立限制。
• 店铺：每个店铺都有独立限制。

例如：每次请求都会同时计入这两个维度。例如，App A 调用 Store 1 时，请求会消耗 App A 与 Store 1 组合的桶容量，也会消耗 Store 1 的桶容量。只有两个桶都有剩余容量时，请求才会成功。

当前桶状态	结果
App A + Store 1 为 39/40，Store 1 为 79/80	请求可以执行。计入后，两个桶分别变为 40/40 和 80/80。
App A + Store 1 为 40/40，Store 1 为 10/80	请求会被节流，因为应用/店铺维度的桶已满。
App A + Store 1 为 10/40，Store 1 为 80/80	请求会被节流，因为店铺维度的桶已满。

应用/店铺维度的默认设置如下：

• 桶大小：每个应用/店铺 40 个请求
• 漏出速率：每秒 2 个请求

店铺维度的默认设置如下：

• 桶大小：每个店铺 80 个请求
• 漏出速率：每秒 20 个请求

为避免被限流，在客户端采用以下做法：

• 为每个店铺维护独立请求队列，避免某个店铺的突发请求影响其它店铺。
• 控制每个应用/店铺组合的请求发送速率，使其低于应用/店铺维度的漏出速率。
• 统计每个店铺的总请求量，使调用同一店铺的所有应用或 worker 合计低于店铺维度的漏出速率。
• 监控每次响应中的 X-Shoplazza-Shop-Api-Call-Limit 响应头。当数值接近桶容量时，在桶满之前主动降速。
• 缓存可复用的响应，尤其是针对同一资源的重复读取。
• 收到 429 时，暂停受影响的请求队列并读取 Retry-After 响应头。等待其指定的秒数后再恢复请求。

漏桶算法

所有 Shoplazza API 都使用漏桶算法管理请求。只要不让桶溢出，应用就可以在一段时间内突发地发出请求。该模型的要点如下：

• 每个应用都有一个可容纳固定数量"弹珠"的"桶"（例如 40 个）。
• 每个 API 请求向桶中投入一个弹珠。
• 桶以固定速率漏出弹珠（例如每秒 2 个），持续腾出空间。
• 如果桶满了，后续请求会失败并返回错误，直到桶漏出足够空间。

速率限制响应头

通过每次 API 响应返回的 X-Shoplazza-Shop-Api-Call-Limit 响应头，可以查看你针对某个店铺已发出的请求数。

X-Shoplazza-Shop-Api-Call-Limit: 32/40

• 32：桶中当前的弹珠数。
• 40：最大桶容量。

计数会随漏出而递减。例如，响应头显示 39/40 后若停止发送请求，10 秒后可能显示 19/40。

Retry-After 响应头指定收到 429 Too Many Requests 响应后重试前需等待的秒数。

处理 429 响应

当请求超过速率限制时，Shoplazza 返回 429 Too Many Requests 错误和 Retry-After 响应头。按响应头指定的秒数等待后再重试。在此期间发出的任何请求都将被节流。

X-Shoplazza-Shop-Api-Call-Limit: 40/40
Retry-After: 2.0