配额与限流：免费层、突发额度与超额计费

免费层给多了会破产，给少了没人愿意试。

一、免费层开了一个月，账单先到了

一位做文档解析 API 的独立开发者，把免费层定成「每月 10 万次」，理由是同行的免费额度看起来都很大。

以下情境为教学假设，人物、引语和数字不代表经核实的真实案例。

第一个月结束，上游推理账单是他预期的 6 倍。查用量才发现，两个账户跑掉了 80% 的请求：其中一个把接口接进了自己的批量处理脚本，另一个在测试爬虫时用了死循环重试。

他既没做限流，也没设硬上限。免费层在代码里只是一个计数器，超过之后继续放行，等着月底结算。于是「免费」这个产品承诺，变成了一张没有签名的账单。

配额是产品参数，也是成本阀门。 同一个数字同时决定三件事：新用户愿不愿意试、老用户什么时候付费、最坏情况下你一个月要垫多少钱。只按其中一件定，另外两件一定出问题。

免费层的成本要能被单价覆盖。 免费用户产生的边际成本，应该由付费用户的毛利覆盖。做不到这一点，免费层就不是获客渠道，而是持续失血的口子。

没有限流的配额不是配额。 一个每月 10 万次的额度，如果在 10 分钟内被跑完，它对成本的保护等于零。额度管总量，限流管速度，两者必须同时存在。

「同行也这么给」不是定价依据。 别人的免费额度背后可能有融资、有更大的毛利空间、有更便宜的上游。照抄数字而不照抄成本结构，等于替别人测试市场。

免费用户也要有身份。 至少绑定邮箱或一个可联系渠道，并记录注册来源。完全匿名的免费额度会被同一批人反复注册，最终变成一次 DDoS 练习。

二、计量口径与免费层设计

计量的第一件事是决定「一次」是什么。选错口径，后面所有阈值都会失真。

按请求计量适合行为稳定的接口。 每次调用消耗的资源接近，客户能靠计数自我管理，支持成本也最低。缺点是它无法区分「查一个字段」和「拉一年数据」的差别，重请求会把成本结构打穿。

按 token 计量适合输入长度差异大的模型类接口。 它和上游成本几乎线性相关，防滥用能力最好。代价是客户必须在响应里看到用量，否则账单无法解释；usage 字段不是可选项。

按任务计量适合异步、长耗时的工作。 一个任务可能跑 3 秒也可能跑 3 分钟，按次收费对客户更直观。但任务粒度必须稳定，否则客户会感觉「同样的活为什么收两次钱」。

免费层的阈值要用真实用量分布来定，而不是拍脑袋。

免费层要覆盖典型用法，不覆盖批量用法。 典型用法是「每天试几次、跑通流程」，批量用法是「一次导入十万条」。前者带来口碑，后者带来账单。区分二者的方法不是看总量，而是看单次会话的请求密度。

额度单位要能对内换算成钱。 按请求计量时，先在内部记下每次调用的平均成本，再反推「1,000 次 = 多少钱」。这个换算不对外公开，但决定了免费层是否可持续。

计量日志要能对账。 每个计费周期保留一份按账户聚合的用量快照，客户申诉时能直接对照。只存总数不存分布，遇到争议就只能各说各话。

阈值调整要留版本记录。 免费额度从 1,000 改到 2,000，老用户按哪个算、什么时候生效，必须写清楚。定价页上的小字和代码里的常量不一致，是这类争议最常见的来源。

三、令牌桶、突发额度与 429

持续速率和突发额度是两个参数，不能只配一个。

持续速率决定长期平均吞吐，比如每秒 5 次；突发额度决定短时间能冲多高，比如允许一次性用掉 30 次。只设持续速率，正常客户在页面加载时的并发会被误杀；只设突发额度，客户可以靠循环把额度瞬间打空。

429 要带可执行的信息。 只返回状态码，客户只能盲目重试；带上 Retry-After 与剩余额度，客户端才能写对退避逻辑。错误体里说明是哪个维度的限制（用户、key、端点），支持成本会下降一大截。

限流要分三层。 按用户限制总量、按 key 限制单凭据、按端点限制高成本接口。三层同时存在时，取最先触发的那一层返回，并在错误体里写明触发维度。

一个客户不能拖垮全站。 单客户占用超过总容量的一定比例时，即使他没超额，也应降级到独立队列。共享池的公平性靠隔离保证，不靠阈值调参。

限流键的选择决定公平性。 只按 IP 限，办公室和云函数的出口会被误伤；只按 key 限，多注册几个账号就能绕过。用户维度做外层总量、key 维度做单凭据、IP 维度做兜底，三层键值缺一不可。

窗口算法要选能解释的。 固定窗口实现简单但边界会双倍放行，滑动窗口平滑但内存开销高，令牌桶在两者之间。对独立开发者而言，令牌桶的可解释性最好：客户问「为什么被限」，可以直接答剩余令牌数。

限流不能吃掉正常重试。 客户端因网络抖动重试，不应该被和恶意刷量同等对待。给 Retry-After 之外的幂等重试留一点余量，或对同一幂等键的重复请求快速返回缓存结果。

四、超额计费、硬上限与滥用防护

超额计费的核心不是定价，而是可解释性：客户要能指着一行账单说「这 1,800 次里，哪 800 次是我超出的」。

硬上限是免费层的默认值。 免费用户没有付费承诺，任何「先用了再说」的设计都会把成本转移给你。硬上限要在接近时提前提醒，比如 80% 和 95% 各发一次，避免突然中断。

软上限适合付费层。 超额部分照常计费，但速度降下来，让客户自己决定是优化调用还是升级套餐。降速比拒绝更容易被接受，也不会让业务在关键时刻断掉。

异常用量要在账单之前被发现。 单日用量超过过去 7 天均值的 3 倍、调用集中在单一端点、请求间隔规律到毫秒、同一 key 出现在多个地理区域，这四类信号都值得先联系客户再处理。

退款与争议的衔接要提前写。 明确「什么算误计费、多久内可申诉、按什么口径退」，比事后逐单谈判省力。可申诉窗口建议 30 天，退款按未使用额度折算，而不是按情绪。

超额要能被预算控制。 至少给客户一个「本月最多花多少」的开关，达到即停。企业客户采购时几乎一定会问这个问题，没有它，很多单子会卡在财务审核。

单价要能覆盖最坏情况。 用最贵的端点、最长的输入、最高的重试率算一遍单次成本，再乘 1.5 的余量作为定价下限。按平均成本定价，遇到一个批量客户就会亏损。

滥用防护和客户成功不是一回事。 识别出异常用量后，先假设是误用，用邮件和文档帮客户修正；只有确认是绕过限制，才升级到冻结。顺序反了，会赶走本来愿意付费的人。

五、行动清单与复算验收

• 明确计量口径（请求 / token / 任务），并在响应体里回传本次用量
• 免费层阈值用真实用量分布确定，P90 落在额度内、P99 明显超出
• 同时配置持续速率与突发额度，并压测过一次真实并发
• 429 响应带 Retry-After、剩余额度与触发维度
• 按用户、按 key、按端点三层限流全部生效
• 免费层默认硬上限，付费层默认软上限并提前提醒
• 四类异常用量信号有告警，且告警早于账单周期
• 超额计费口径、申诉窗口与退款规则写进文档与定价页

清单前半段决定「会不会被判超额」，后半段决定「超额之后好不好解释」。两段都要过一遍，只做限流不做账单说明，争议会转移给支持邮箱。

验收标准：任取一个免费账户，能说清它在什么条件下会被拒绝、被拒绝时看到什么、升级后额度如何变化；任取一张账单，能逐行还原出「配额内多少、超配多少、单价多少」。

免费层覆盖率 = 免费额度 ÷ 典型活跃用户月用量
示例：1,000 ÷ 600 = 167%（够用）；1,000 ÷ 1,500 = 67%（多数用户会触顶）
超额收入 =（实际用量 − 配额）× 单价
示例：（1,800 − 1,000）× 0.02 = 16 美元
限流阈值建议取 P95 用量的 1.5–2 倍

使用边界与实操验收

本文讲免费层与超额计费的产品口径，令牌桶的具体实现见 《AI Agent 工程实战》6.3 限流与配额：按租户 token 预算的令牌桶 。套餐如何横切、每档放什么功能，见 三档套餐：把「刚好够用」写成一张表 ；本文只讲配额机制与 429 行为。

演练方式：用一个免费账户写脚本在 10 分钟内打满额度，观察是否在预期时刻返回 429、响应头是否齐全、告警是否在 5 分钟内到达。再模拟一个批量客户，确认他的流量不会影响另一个正常账户的 P95 延迟。

本文不讨论按座位、按存储或按并发连接的计费模型，也不涉及企业合同里的承诺用量折扣。那些属于套餐设计与商务谈判的范围，本文只覆盖「按调用计量」这一条主线。

关键参考与核验范围

以下链接支持对应的机制说明；本文的额度、单价与账单数字均为教学假设，不代表任何平台的真实定价。核验日期：2026-10-25。

• IETF RateLimit headers 草案 ：RateLimit-* 头的字段语义与组合方式，可作为响应头设计的参照。
• Google API 配额说明 ：区分配额与速率限制、按项目与按用户配置的官方口径。

系列导航

• 上一篇：API key 管理：签发、最小权限、轮换与泄露响应
• 下一篇：对外 Webhook：事件签名、重试、幂等与死信队列
• 回到目录：一个人把 API 做成产品：对外接口、开发者体验与支持
• 相关阅读：《AI Agent 工程实战》6.3 限流与配额：按租户 token 预算的令牌桶 、三档套餐：把「刚好够用」写成一张表