Claude Code 结构化用量限额行（Structured Usage Rate-Limit Rows）：limits[] 字段的服务器权威语义与客户端渲染契约-开发者社区

文档
提示工程
人工智能

【免费下载链接】claude-code-system-prompts

All parts of Claude Code's system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.

项目地址：https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts

点击查看免费下载

Claude Code 的系统提示词仓库（claude-code-system-prompts）中的>{"extra_usage": {"is_enabled": true, "monthly_limit": 50000, "used_credits": 27140, "utilization": 54, "currency": "USD"}, "limits": [{"kind": "spend", "group": "monthly", "percent": 54, "resets_at": "2026-10-01T00:00:00.000Z", "severity": "normal", "is_active": true}]}

其中limits数组的每一行包含：kind（配额类型，如spend）、group（周期分组，如monthly）、percent（0–100 的整百分比，超限可超过 100）、resets_at（ISO 8601 UTC 重置时刻）、severity（严重级别）以及is_active（标记该行所属的金额）。该文档同时说明：无配额的账号返回{"limits": []}。

二、核心契约：meters 的权威在服务器，客户端只负责原样渲染

本字段最关键的一句话是："which meters apply, their scope, labels, severity and order are the server's"——哪些 meter 生效、它们的作用域、标签、严重级别以及排列顺序，全部由服务器决定。由此推出两条直接约束：

客户端必须逐字渲染（render verbatim）：客户端不得按自己的规则对行重排、改名或改变严重级别语义，limits[]呈现的就是服务器的判定。
新增 meter 不需要客户端发版：服务器可以随时加入新的 meter 行（新的kind/group/severity组合），旧版客户端依然能正确展示，因为渲染逻辑不依赖对某个具体 meter 的硬编码认知。这与网关协议中"Don't reject what you don't recognize"（data-claude-code-gateway-protocol.md）的向后兼容原则一脉相承。

这种"服务器权威 + 客户端透明"的设计，把配额语义的演进成本全部收敛到服务端，客户端 UI 只需是一个忠实的中转层。

三、`null`与`[]`：两种"无数据"的精确语义

该字段用三种状态区分"没有用量行"的不同成因，这也是最容易误用的部分：

[]（空数组）：服务器已支持usage 端点且明确报告了"没有 meter"——例如账号本身没有任何配额约束，网关对无配额用户返回{"limits": []}（见上文网关协议示例）。
null（响应体完全没有 rows）：服务器先于该能力存在（"a server that predates them"），即旧版服务端根本不在响应体中携带 rows 字段。此时是能力缺失，而非"没有限额"。
null（fetch 失败时）：usage 请求正在进行或失败期间，该字段同样为null。

第三点在语义上很微妙，需要与"快照"严格区分：该字段只反映服务器当前的回复（"the rows here are only ever the server's current reply"）。它绝不包含以下两种数据：

CLI 根据 rate-limit 响应头自行构建、用于自身屏幕的那一行；
客户端对更早一次回复的本地快照。

换句话说，这是一个"活值"字段：fetch 失败时它归null，而不是退回上一次成功的结果。UI 需要据此处理"数据尚未就绪/拉取失败"状态，而不是展示过期数据。

四、两条数据通道的分工：结构化 rows 与响应头

要理解该字段为什么严格排除"CLI 从响应头构建的行"，需要对照仓库中速率限制头相关文档。Claude Code 实际存在两条并行的用量数据来源：

通道一：usage 端点的结构化limits[]（本文主题）——面向账号/网关级配额的完整描述，含金额（extra_usage）、周期、重置时间、严重级别等结构化字段，供/usage面板与状态行展示。

通道二：anthropic-ratelimit-unified-*响应头——每次POST /v1/messages响应携带的实时限额状态。data-claude-code-gateway-protocol.md 列出了这些头的完整语义：

响应头	含义
`anthropic-ratelimit-unified-status`	`allowed`，越过阈值后为`allowed_warning`
`anthropic-ratelimit-unified-representative-claim`	`overage`或`5h`/`7d`（滚动窗口，客户端做时间运算，勿当日历预算）
`anthropic-ratelimit-unified-overage-utilization`	已用额度占比（两位小数，允许请求期间保持在 1 以下）
`anthropic-ratelimit-unified-overage-surpassed-threshold`	越过 75% 时为`0.75`、95% 时为`0.95`，用于触发客户端提示
`anthropic-ratelimit-unified-reset`/`-overage-reset`	配额重置时刻（Unix 秒）

data-rate-limit-unified-windows.md 进一步说明：5 小时、7 天与含超额的每周（per-model bucket）窗口均从这些头读取，utilization与顶层字段同尺度（通常 0–1，超出 1 表示合法超出上限，如低优先级任务越过 5 小时限额）；且窗口在每次观测时都记录，事件在百分比或重置时间变化时即触发，而不只发生在状态迁移时。同时>