配额与速率限制

FreeMaint API 强制执行每个公司的每日配额，并在 UTC 午夜重置。上限取决于您的级别；计数器和剩余内容作为响应标头公开。

每日上限

• Core、Starter — 0（API 密钥需要 Business）
• Business — 每天 5,000 次调用（GraphQL 与能耗数据接入端点共用同一计数器）
• Enterprise — 每天 100,000 次调用
• On-Premise — 无限制（上限 = null）

响应标头

• X-RateLimit-Limit — 您的等级的每日上限
• X-RateLimit-Remaining — 今天剩余的呼叫（每个配额计数的呼叫减少）
• X-RateLimit-Reset — UTC 午夜的 Unix 时间戳（下次重置）

什么不算数

只有 /public-api/whoami 是免费的：它不会减少你的计数器，因此你可以在不消耗配额的情况下验证密钥及其套餐。经过 /api/v1/graphql 的一切都会计入配额，包括 whoami 查询，能耗数据接入端点同样计入。

什么算作一次调用

计数按操作递增，而不是按 HTTP 请求。把 50 个带别名的写操作放进同一个请求，仍然消耗 50 个额度。因此合并请求节省的是网络往返，而不是配额。要让周期性同步开销可控，请用 parts(updatedSince: "...") 只取变更部分，而不是重新读取整个目录。

当您超过上限时

达到每日上限后，之后的每次调用都会被拒绝，并返回消息「Daily API cap reached」。在 REST 接口（/public-api/ping、能耗数据接入端点）上，这是一个 HTTP 403。在 GraphQL 上，HTTP 状态是 200，拒绝信息位于 errors[0].extensions.code = FORBIDDEN，其中 originalError.statusCode = 403。计数器在 UTC 00:00 重置。没有软上限、没有突发额度，也没有按分钟的窗口——窗口就是一天。