Etsy API 速率限制与配额管理规划

日期: 2026-03-29
API 配额: 5 QPS / 5,000 QPD
文档类型: 技术规划

---

核心结论

QPD（5K/天）是硬天花板，QPS 相对宽松。

• QPS 理论上限: 5 × 86,400 = 432,000/天（远超 QPD）
• QPD 实际可用: ~208/小时，~3.5/分钟
• 策略: 按 QPD 做平滑分配，QPS 几乎不会触顶

---

场景配额分配

场景 A：基础运营（保守型）

适合中等规模店铺：

功能	频率	日消耗	说明
新订单检测	每 5 分钟	~288	及时响应订单
库存同步	每 15 分钟	~96	防止超卖
商品状态检查	每 30 分钟	~48	下架/价格变动
小计		~432	余量充足

场景 B：竞品监控（主力型）

监控 N 个竞品价格变动：

监控数量	检查频率	日消耗	策略
50 个	每 2 小时	600	低频广撒网
100 个	每 4 小时	600	平衡型
200 个	每 6 小时	800	监控更多 SKU
50 个	每小时	1,200	高频盯盘（贵品）

场景 C：全量同步（爆发型）

一次性拉取全店数据：

• 假设 300 个 listings
• Etsy 分页: 100 条/页
• 需 3 次请求拉全量
• 每日可做 ~16 次全量同步

---

速率控制策略

1. 令牌桶算法（推荐）

// 按天配额平滑分配
const DAILY_QUOTA = 5000;
const SMOOTHING_INTERVAL = 60 * 1000; // 1分钟

// 每周期可用: 5000 / 1440 ≈ 3.47 请求/分钟
// 实际可设: 3 请求/分钟缓冲，留余量应对突发

2. 优先级队列

enum Priority {
  CRITICAL = 1,  // 订单确认、支付回调 — 立即执行
  HIGH = 2,      // 库存同步、价格更新 — 5分钟内
  NORMAL = 3,    // 商品信息刷新 — 按配额平滑执行
  LOW = 4        // 竞品监控 — 闲时执行
}

3. 动态频率调整

• 忙时（日本时间 10:00-22:00）：降低竞品监控频率，优先订单
• 闲时（凌晨）：批量做竞品扫描、数据报表生成

---

防御性设计

风险	防护措施
突发流量	请求队列 + 指数退避重试
配额耗尽	每日 00:00 UTC 重置，提前预留 10% 缓冲
API 失败	本地缓存 + 失败降级（用本地数据）

---

建议起步配置

• 订单检测: 5 分钟/次
• 库存同步: 15 分钟/次
• 竞品监控: 20-50 个 SKU，每 4 小时/次
• 每日预留: 20% 余量（~1000 次）应对突发

---

下一步行动

1. [ ] 实现 API 调用调度器（令牌桶 + 优先级队列）
2. [ ] 设计 Etsy 模块数据结构（listing、order、竞品）
3. [ ] 搭建竞品监控原型（价格变动追踪）
4. [ ] 集成到 Crystal ERP 的现有架构中

---

相关文档:

• Crystal ERP 架构设计
• Crystal ERP 实施计划