配额与限速规则

Keepamore 对所有调用实施三级配额控制：每分钟限速、每日额度、每月额度。三者任一触顶都会被限流并返回 429。

三级窗口

维度	作用	触顶时响应
每分钟限速（minute）	保证服务运行平稳	QUOTA_MINUTE
每日额度（day）	每日限速	QUOTA_DAY
每月额度（month）	套餐周期内的总额度	QUOTA_MONTH

具体配额数值由你购买的套餐、数量决定，可在使用统计页查看当前余量。

计费顺序

调用示意，任何一步失败都不会扣费：

1. 鉴权 API Key
2. 参数解析与校验（失败 → 400）
3. 检查并预扣 minute / day / month 额度
   └─ 任一不足 → 报 429 错误：QUOTA_xxx
4. 执行业务
5a. 成功 → 返回业务数据，成功扣费
5b. 失败 → 返回 errorId，不扣费

短时间（几分钟）内相同请求命中缓存不重复计费。

闲时套餐和通用套餐

• 只购买了通用套餐：所有请求走通用套餐
• 只购买了闲时套餐：闲时窗口（19:00–07:00），扣闲时套餐额度；非闲时，无法调用
• 已购买闲时 + 通用：
  • 闲时窗口（19:00–07:00）内 → 优先扣闲时额度
  • 闲时额度耗尽 或 非闲时窗口 → 扣通用套餐额度，响应 metadata 字段 fellBackToGeneral: true

响应示例：

{
	"code": "0000",
	"msg": "ok",
	"data": {
		/* ... */
	},
	"metadata": {
		"plan": { "type": "general", "name": "通用套餐" },
		"fellBackToGeneral": false,
		"unitsConsumed": 1,
		"quotaHint": {
			"minute": { "limit": 20, "remaining": 15 },
			"day": { "limit": 2000, "remaining": 1800 },
			"month": { "limit": 10000, "remaining": 8000 }
		}
	}
}

每次成功调用都会带上 quotaHint，客户端可据此做自适应限速。

套餐余量用完、到达限速

• minute 触顶：稍等 60 秒内自动恢复；升级套餐数量
• day 触顶：等待北京时间次日恢复；升级套餐数量
• month 触顶：等待下个计费周期恢复；升级套餐数量

免费接口

以下调用不消耗 units（但仍然需要有效 API Key）：

• GET /api/token / MCP keepa_get_quota：查询额度
• MCP keepa_time_convert：keepa minute和时间戳转换

最佳实践

• 批量请求时读 quotaHint.minute.remaining，接近 0 时主动 sleep
• 捕获 429 + QUOTA_MINUTE 后指数退避重试（起始 1s、上限 30s）
• 通用套餐结合闲时套餐，更省成本

---

下一步：使用统计与扣费日志 · 通用错误码