treg 402状态码机制深度解析Agent如何自动处理余额不足【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/tregtreg 是 Agent 工具界的 “OpenRouter”——让 Agent 用一个 token 就能调用 60 供应商、3000 数据 API 的统一网关。当团队的预付余额不足以支付某次调用时treg 返回402 状态码且响应体完全机器可读Agent 可以自动完成充值、换键或降配等恢复动作。本文带你从余额闸门讲到响应体字段完整拆解 treg 的 402 机制与 Agent 自动处理策略。treg 中的 402 是什么何时返回、何时绝不返回HTTP 402Payment Required是协议为“需要支付”专门定义的状态码treg 正是把它在 Agent 世界里做出标准实现的典型团队预付余额不够支付本次调用。先划清三个边界只有走 treg 自家 key 计费metered的调用才会 402。团队一旦为某供应商连接了自己的 API key自己的 key 永远优先于 treg 的这类调用永不计费自然不会有 402402 本身从不扣钱预扣要么直接失败不产生任何 Hold 记录要么已开的 Hold 全额释放 新团队创建时自带$1.00 免费额度可以先跑通几次真实调用再谈 402。源码里的状态码映射把 402 归类为balance类型与auth401、policy403、resolution404分庭抗礼见 src/treg/application/call/service.py。余额闸门一条 SQL 决定要不要 402402 机制的核心是预扣reserve。treg 的账务体系全程使用整数 micro-USD1 micro 一百万分之一美元计费——一次目录调用的成本约 600 micro用美分都表达不了。预扣只有一条条件 UPDATEUPDATE org SET balance_micro balance_micro - :est WHERE id :org AND balance_micro :estWHERE 子句是检查SET 子句是扣款——由数据库本身决定谁拿到最后一分钱。更新行数为 0 时抛出 InsufficientBalance调用方把它翻译成 402 响应。这个设计有两个漂亮的性质零锁竞争没有“先 SELECT 再 UPDATE”、没有应用层锁SQLite 和 Postgres 行为一致。N 个 Agent 并发请求、余额只够付 K 次结果恰好是 K 次成功、N−K 次 402数字精确402 响应体同时携带团队当前余额与本次调用所需成本见 insufficient_balance 402 构造Agent 拿到的是可计算的数字而不是一句“余额不足”。402 响应体解剖为机器而生的设计treg 官方的 Agent 上手文档 llms.txt 一句话点题402 携带machine-actionable body机器可执行响应体——Agent 不必读散文直接按 JSON 字段行动。典型响应体长这样{ detail: { error: insufficient_balance, balance_micro: 800000, estimated_cost_micro: 1200000, topup_url: /app#billing, autotopup_enabled: false, provider: moz, endpoint_id: moz.web.backlinks.summary, message: moz.web.backlinks.summary would cost ~$0.0012 ... balance is $0.80. } }每个字段各司其职字段含义Agent 如何用它error错误类型insufficient_balance余额不足或route_max_cost超单次成本上限balance_micro团队当前余额micro-USD与预估成本对比判断“差多少”estimated_cost_micro本次调用需预扣金额决定是重试、拆分请求还是放弃autotopup_enabled自动充值是否开启开启时 402 多半是冷却/月上限所致无需人工message人读摘要内嵌每条恢复路径的具体命令注意还有第二来源的 402——route_max_cost调用方通过X-Treg-Route-Max-Cost头设置了单次成本上限而本次预估成本超过它时treg 同样以 402 拒绝且本次尝试不计分文reserve.py。这是给 Agent 的“花费护栏”402 在这里意味着“请求太贵请减少行数/目标数”而不是“去充值”。Agent 自动处理 402 的 4 条恢复路径402 被设计成“可执行错误”message字段按优先级列好路径Agent 逐条执行即可。1️⃣ 先查账treg balance余额接口返回当前余额、在途 Hold 与近期消费。CLI 甚至在收到 402 后自动补一句提示“(check the balance withtreg balance, add funds withtreg topup)”——人类和 Agent 看到的是同一份 JSON 两条命令CLI 402 提示。2️⃣ 手动充值treg topup一条命令进入结算页仪表盘 Team → Billing 页面同样可充值大额充值还带阶梯赠送。3️⃣ 开启自动充值treg topup --auto on --threshold 5 --amount 20余额跌破 $5 自动补 $20内建冷却时间与月上限防失控。细节很妙开了自动充值后402 响应体还会写明金额、阈值、冷却与月上限——开了自动充值却仍被 402 拦截说明被冷却或上限卡住message会直接给出调大参数的命令treg topup --auto on --amount 50 --cap 500而不是让人误以为“自动充值坏了”。4️⃣ 连接自己的 keytreg connections connect --provider provider这是治本路径走自己 key 的调用永不计费402 从此消失。MCP 通道Agent 最常用的工具接口对 402 还做了特殊处理剥离转发响应体里的一切topup_url与支付链接mcp.py 402 处理支付链接清洗逻辑以遵守平台的数字商品策略但保留诊断数字和提示语 “the teams prepaid balance is not enough for this call”——诊断还在拉你去付款的链接没了。于是 402 在 Agent 世界的闭环是读 JSON → 算数字 → 三选一查账 / 充值 / 连自己的 key→ 重试原调用全程无人工。若团队反复手工撞上 402treg 还会发一封点明原因和唯一解法的通知邮件email.py。一张表分清 402、429、503到底是谁的问题Agent 遇到拒绝响应的第一步是归因——是否重试、去哪重试、是否计费全看这一分类状态码错误类型谁的问题是否计费Agent 该怎么办402insufficient_balance团队余额不足团队的❌ 不计费充值或连接自己的 key402route_max_cost超过调用方成本上限调用方的❌ 不计费减少行数/目标数或调高上限429platform_daily_cap_reached团队当日支出封顶团队的❌ 不计费等 00:00 UTC 重置或用自己的 key429trial_allowance_reached供应商免费试用额度用尽团队的❌ 不计费等次日重置或连接自己的 key503provider_capacity_unavailabletreg 自家供应商账户额度耗尽treg 的❌ 不计费约 1 分钟后重试或换响应体里的替代供应商其中 503 与 402 最易混淆值得单独强调它是treg 平台账户欠费不是你的团队余额——什么都没收你的钱响应体给出resets_at与替代供应商列表treg 约每分钟探测一次供应商健康隔一分钟重试可能成功。而在结算逻辑里402 属于“不是调用方过错”的状态集合被 402 拒绝的调用其预扣 Hold 全额释放零计费。避免 402 的 5 条实操建议批量任务前先跑treg balance——看一眼余额 × 单次单价就能算出还够跑多少步开自动充值——阈值与月上限按日均消耗设置多数 402 会在无人干预下自愈设置每日支出上限——上限是 fail-closed 的触顶返回 429 而非静默超支为失控 Agent 的爆炸半径封顶高频供应商连自己的 key——重度使用的供应商走自己的 key彻底脱离计费传X-Treg-Route-Max-Cost——给单次调用设成本上限异常昂贵的调用被 402route_max_cost拦下且不计费。源码导航去哪里读 402 机制想深入实现从这几个文件切入文件看什么src/treg/domain/money/init.py唯一“动钱”的代码路径余额闸门的那条条件 UPDATEsrc/treg/application/call/reserve.py402 响应体的构造含自动充值提示行src/treg/web/llms.txtAgent 上手文档里 402 与恢复路径的官方定义src/treg/mcp.pyMCP 通道为何要清洗 402 里的支付链接docs/context/architecture/money.md账务系统完整设计账本、预扣、结算、释放402 是 treg 最有代表性的状态码它既是资金侧的 fail-closed 闸门又是写给机器的错误消息让 Agent 把“没钱了”从任务中断变成一次自动可恢复的分支。这正是 treg 能直接挂进 Agent 主循环的原因——每个拒绝响应都自带数字和下一步Agent 永远不需要猜。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考