使用统计与扣费日志

每一次成功/失败的 API 或 MCP 调用都会记录到使用日志（usage_log），用于扣费对账、性能排查和异常定位。

能看到什么

主站查看（图形化）

前往 Keepamore 主站 /keepamore-api 页的 使用统计 标签页，可看到：

• 通用套餐、闲时套餐当前周期的配额进度条
• 每日请求数与 units 消耗趋势图（支持切换 7 / 30 / 90 天）
• 分页的请求日志表格：时间、工具/端点、units、成功/失败、耗时、来源（API/MCP）

接口查询（程序化）

• GET /api/quota — 查询当前额度状态（不扣费） 参见 API 端点 · quota
• MCP 工具 keepa_get_quota — 同上，在 MCP 内调用

每次调用返回的 metadata

所有成功响应都带 metadata 字段，字段含义：

字段	含义
responseTime	服务端从接收到响应的总耗时
plan.type	本次扣费的套餐类型（general / off_peak）
plan.name	被扣费套餐的名称
fellBackToGeneral	是否因闲时额度不足或非闲时窗口而回落到通用套餐
unitsConsumed	本次实际扣费 units
quotaHint.minute/day/month	各级窗口当前剩余量
keyWarning	可选；如"旧 Key 还有 5 分钟失效"等提醒

二进制响应（如 graphimage 返回 PNG）会把元数据放到 HTTP 头：

• X-Response-Time
• X-Units-Consumed

失败调用的 errorId

当调用因下游失败或内部异常报错时，客户端只会收到：

{
	"code": "EXECUTION_ERROR",
	"msg": "下游调用失败，请联系技术支持并提供 errorId",
	"data": null,
	"errorId": "a1b2c3d4-…"
}

详细堆栈、请求参数、下游响应都在服务端数据库中关联 errorId 留存。联系支持时请带上 errorId，否则无法快速定位。

字段详解（usage_log 表）

开发者向支持反馈对账问题时可能被要求提供以下字段值：

字段	说明
user_id	账号 ID
api_key_id	本次调用使用的 Key 主键（不是 Key 本身）
subscription_id	本次扣费的订阅 ID
source	api 或 mcp
plan_type	general / off_peak
action	工具/端点名，如 keepa_get_product
units_consumed	扣费数量
success	是否成功
error_code	失败时的错误码（与 errors 对应）
response_time_ms	响应耗时（毫秒）
ip_address	调用方 IP（取 X-Forwarded-For 第一段）

常见对账问题

Q：我看到扣费了但返回是失败？ 检查 error_code：若为 QUOTA_*，说明被限流，此时 units_consumed=0，不产生实际扣费；若为 EXECUTION_ERROR 等业务异常，day/month 会自动回滚，不计入你的预算。

Q：为什么两个通用套餐都有额度时只扣了一个？ 同一 plan_type 下一个账号只保留一个 active 订阅，升级/换套餐时会合并到新订阅。

---

下一步：通用错误码