Billing black holes: when the error message lies about what your quota is doing — 10+ reports, one taxonomy ask

[nanami-0713]

TL;DR. Across the 0.1.6/0.1.7 storms one family of reports keeps repeating: the error you see is not the failure you are paying for. Misclassified errors turn quota into a black hole — requests keep being retried (and billed) while the UI names an unrelated cause. This post consolidates the reports into one table and asks for a small protocol surface: truthful error classes + visible spend.

The evidence (0.1.6-alpha.2 → 0.1.7-rc.2 unless noted):

What the user sees	What actually happened	Cost shape	Refs
"API key invalid"	Request body over the gateway limit — the key is fine	You debug auth while the real failure is payload size	#7799
TRANSPORT timeout, endless retries	Clean 413 from an unbounded request body (session log) mapped into retryable TRANSPORT, retried 5× ≈ 240 MB per round (fixed in rc.2, #5168)	Paying repeatedly for the same oversized payload	#7753, #7658, #7736
Cache misses; long sessions get slower and pricier	Compaction drops reasoningEffort → KV cache bust → full-price re-read	Long sessions pay the cache-rebuild tax again and again	#7794, #7588
"Ordinary error"	Compaction timeouts (HTTP 124) misclassified as ordinary failures	Compaction failed, upstream budget still burned	#7632
Usage blind spot	web_search spend does not appear in session logs	Per-request spend invisible exactly where it happens	#7195, #7189, #7494
"Quota looks fine"	Quota-shape table misses FreeTierOnly / arrears states	Cannot tell "quota left" from "quota dead"	#7649
Balance −$0.24 after 20.8M tokens, no output	402 mapped into retryable space, no balance guard	Money gone with no early stop	#7052, #7053

The ask (extending #6895, "subscription-window quota as a first-class citizen"):

1. Distinct terminal error classes: QUOTA / BALANCE / PAYLOAD_LIMIT / AUTH must not share a bucket with TRANSPORT. PAYLOAD and QUOTA are not retryable — retrying them is paying five times for one failure.
2. A per-request cost surface in the session (the cost badge already asked for in Idea: a conversation stats/header slot so plugins can render cost or context badges #7399/什么时候能在对话框的底部加入一个余额显示的功能 #7262): model × time segment × price, including gateway-side tool calls.
3. A balance/quota guard: end the turn loop when balance is exhausted (402 → terminal), and surface remaining quota, including subscription windows.
4. web_search spend in the session log, so dashboards can see it.

Community tooling (dsh-usage-style dashboards: #6896, prior art #2028/#6533/#5383/#1280) can only show what the session log contains. The fix for the black hole has to land in the protocol surface itself: truthful errors + visible spend.

---

TL;DR. 0.1.6/0.1.7 风暴里反复出现同一类报告:你看到的错误,不是你在为之付费的那个失败。错误归类失真把额度变成黑洞——请求在被重试(计费),界面却报出一个不相干的原因。本文把相关报告整合成一张表,并向官方要一个很小的协议面:真实的错误分类 + 可见的开销。

证据表(除注明外均为 0.1.6-alpha.2 → 0.1.7-rc.2):

用户看到的	实际发生的	钱的形态	出处
「API 密钥无效」	请求体超过网关上限,密钥本身没问题	排查方向被带偏,真实原因是载荷超限	#7799
TRANSPORT 超时、无限重试	无上限请求体(session log)导致干净 413,被归入可重试的 TRANSPORT,每轮重传 5 次约 240 MB(rc.2 已修 #5168)	同一个超限载荷反复付费	#7753/#7658/#7736
缓存未命中,长会话变慢变贵	压缩丢 reasoningEffort → KV cache 失效 → 全价重读	长会话反复支付缓存重建税	#7794/#7588
「普通错误」	压缩超时(HTTP 124)被误判为普通失败	压缩失败,上游预算照烧	#7632
用量盲区	web_search 计费不进会话日志	开销恰好发生在不可见的地方	#7195/#7189/#7494
「额度还有」	quota 形态表缺 FreeTierOnly / arrears 状态	分不清「还有额度」和「额度已死」	#7649
跑完 20.8M token 余额 −$0.24、无产出	402 被映射进可重试空间,无余额闸门	钱烧完、无人喊停	#7052/#7053

诉求(扩展 #6895「订阅窗口额度应为一等公民」):

1. 可终止的错误分类:QUOTA / BALANCE / PAYLOAD_LIMIT / AUTH 不与 TRANSPORT 混桶;PAYLOAD 与 QUOTA 不可重试——重试它们等于为同一次失败付五次钱。
2. 会话内的逐请求成本面(Idea: a conversation stats/header slot so plugins can render cost or context badges #7399/什么时候能在对话框的底部加入一个余额显示的功能 #7262 已在要的 cost badge):模型 × 时段 × 价格,含网关侧工具调用。
3. 余额/额度闸门:余额耗尽时结束回合循环(402 → 终态),并显示剩余额度,含订阅窗口。
4. web_search 开销写进会话日志,让各面板看得见。

社区工具(dsh-usage 类面板:#6896,先例 #2028/#6533/#5383/#1280)只能显示日志里有的东西;黑洞的修复必须落在协议面本身:诚实的错误 + 可见的开销。

[nanami-0713]

Update (2026-09-27) — three new rows for the taxonomy, all worse than "wrong error message":

• [Bug][0.1.7-rc.2] goal-round-driver + broken compaction caused runaway 642M token explosion in a single session (Continuing goal infinite loop) #7894 — a runaway that only showed up in the provider dashboard. On rc.2, three compounding bugs (unthrottled goal-round-driver auto-continue + broken compaction) drove 4 sessions to 1.2B tokens combined, one single session at 642M over 7+ hours — found by hand-decompressing raw session.v4.jsonl.zstd logs, not by any UI surface. Strongest single data point yet for ask #3 (balance/budget guard, hard kill) and for per-request usage surfacing.
• [Bug][0.1.7-rc.2] Failed turn (HTTP 400/429) leaves all-zero usage samples; contextPressure projection permanently zeroed — ContextMeter shows 0% #7972 — failed turns write all-zero usage samples that poison the meter. An HTTP 400/429 placeholder {0,0,0} gets folded by the contextPressure projection and permanently overwrites the last good value (the projection-cache checkpoint sits at the session tail, so the zero is never recomputed). Billing-adjacent in the worst way: the meter doesn't just miss spend after an error, it actively forgets real state.
• dsh-llm-pi-ai drops Retry-After, so 503/429 retries fall back to a 500 ms local backoff #7926 — provider pacing advice is dropped. providerRetryAfterMs exists and dsh-llm-retry honors it, but only the deepseek adapter fills it in; llm-pi-ai routes lose the Retry-After header, so 503/429 storms run on a 500ms→10s local backoff — burning attempts (and quota) against a server that explicitly asked to slow down.

The pattern across all three: errors don't just fail to report usage, they distort it — zero-samples overwriting good state, unadvised retry loops, runaway continuations. That's asks #1 and #3 restated as one design rule: the ledger must be monotone under errors — an error may pause the meter, never rewrite it.

---

中文摘要： 三条新证据——#7894（rc.2 三 bug 叠加，4 会话共 12 亿 token，单会话 642M/7 小时+，靠手工解 zstd 日志才发现）、#7972（失败 turn 写入全零 usage 样本，永久覆盖最后一次有效 contextPressure，投影缓存检查点在会话尾部导致永不重算）、#7926（只有 deepseek 适配器回填 Retry-After，llm-pi-ai 路线丢失，503/429 用本地 500ms→10s 退避硬冲）。三条合起来是同一设计规则：账本在错误下必须单调——错误可以暂停计量，但不能改写它。