AI API 额度、限流与错误处理

total spending capacity of an account is shaped by three distinct credit controls. The first is the account balance, which represents the aggregate of all prepaid credits available across the platform. If this balance falls below zero, even requests to free models will be rejected with a 402 status. The second control is the per-key credit limit, an optional cap that can be applied to an individual API key. This limit is defined by three fields in the key metadata: `limit` sets the total cap, `limit_reset` indicates when the cap will refresh, and `limit_remaining` shows how much of the cap is still available. The third control is the in-flight spending budget, a mechanism designed to prevent concurrent requests from collectively exceeding the account's balance before any of them have finished processing.

The in-flight spending budget operates by estimating the token cost of a request before it is sent to a provider. This estimate is calculated using the input tokens plus the completion tokens allowed by the `max_tokens` parameter, up to a fixed per-request ceiling if `max_tokens` is not specified. Only token prices are factored into this calculation; per-request fees, plugin charges, and image pricing are excluded. If a request has no token component, no hold is placed on the budget. The estimated cost is held against the account while the request is active. Once the request completes or fails, the hold is replaced by the actual cost for a brief settlement period before being released. The total amount that can be held at once is determined by a fraction of the current credit balance, capped at a fixed maximum. If a new request's estimated cost cannot fit within this budget alongside existing active and recently completed requests, it is rejected with a 402 error before reaching a provider. The error metadata will specify whether the budget is exhausted due to existing requests (`in_flight_budget_exhausted`) or because the single request is too expensive (`weight_exceeds_budget`). In the former case, a `Retry-After` header is provided, as the condition is transient. In the latter, reducing the prompt size or `max_tokens` is the only viable solution without adding credits. This budget only applies to prepaid accounts with balances below a certain threshold or newer accounts without a established spending history. Accounts with balances above the threshold, as well as enterprise or invoice-billed accounts, are exempt.

Budget controls are organized into a hierarchy of spending caps, checked in a specific sequence on every paid request. The first layer consists of guardrail budgets, which are defined by a `limit_usd` and a `reset_interval`. These are applied at the workspace default level, the member level, and the individual API key level. The spend is tracked against the combined total of the member and then against the key's own spend. The second layer is workspace budgets, which cap the total spend of an entire workspace per interval. The third layer is the key's own limit, which is the `limit` field mentioned earlier, enforced once its specific time window is exhausted. All time intervals are based on UTC. A daily budget resets at 00:00 UTC, a weekly budget on Monday at 00:00 UTC, and a monthly budget on the first day of the month at 00:00 UTC. A lifetime workspace budget does not reset.

To inspect these budgets, the `GET /api/v1/key` endpoint provides a `budgets` array. This array lists every applicable budget, showing the enforcement count, the remaining amount in USD, and the reset time. The `effective_budget` field identifies which budget will block a request first. If a budget is already spent, it is the one that triggers the rejection. If no budget is fully spent, the entry with the least `remaining_usd` is considered the effective budget. When a request is blocked by a budget, it fails with a 403 status before reaching a provider. The error message names the budget and includes the relevant figures. The `error.metadata` object provides structured details: `limit_source` identifies the type of budget (guardrail, workspace, or key limit), `scope` matches the scope value from the `budgets` array, and `resets_at` gives the ISO 8601 UTC timestamp for the window rollover, or `null` for a lifetime budget. Since the wait time is typically hours or days, no `Retry-After` header is sent. Proactive monitoring of `effective_budget.remaining_usd` via the key endpoint is recommended to avoid mid-task failures.

请求限流的规则与响应头

OpenRouter 的请求限流主要针对两类场景：免费模型的使用额度和 DDoS 防护。免费模型变体（ID 以 `:free` 结尾）受两个维度限制：每分钟请求数和每日请求数。具体阈值取决于账户累计购买的代币数量。若累计购买少于 10 个代币，每分钟最多 20 次请求，每日最多 50 次；若累计购买达到或超过 10 个代币，每日上限提升至 1000 次，每分钟限制仍为 20 次。值得注意的是，系统在实际执行时会略有宽容：当账户累计购买达到 9 个代币时，即按高额度策略处理，但接口返回的 `is_free_tier` 字段可能仍显示为 `false`，同时返回较高的每日限额值。

这些限制通过 HTTP 响应头中的 `X-RateLimit-*` 系列字段暴露给调用方。当请求触发限流时，服务器返回 HTTP 429 状态码，并在响应头中附带当前限额、剩余配额、重置时间等信息。调用方应优先读取 `Retry-After` 头部，该字段明确指示了需要等待的秒数。对于免费模型，每分钟的限流值不会在 `GET /api/v1/key` 接口的响应中直接体现，仅能通过实际请求被拒后的响应头获取。

DDoS 防护由 Cloudflare 层面执行，当请求频率或模式被判定为异常时，会直接拦截并返回 429。这类拦截通常没有明确的配额说明，响应头中可能不包含标准的限流元数据。此时应降低请求频率，避免短时间内集中发送大量请求。

当限流发生时，错误响应体遵循标准错误格式。若限流来自 OpenRouter 平台自身，`error.metadata` 中会包含具体原因；若来自上游服务商，则 `error.metadata.provider_code` 会携带服务商返回的原始错误码。对于服务商侧的限流，系统会自动尝试 fallback 路由，将请求切换至其他可用服务商，只有当所有候选服务商均不可用时，才会将 429 返回给调用方。

在流式响应场景下，若限流发生在数据传输过程中，错误不会以 HTTP 429 形式返回，而是通过 SSE 事件流中的 `finish_reason: "error"` 传递。这是因为服务器已发送 HTTP 200 状态码，无法再更改响应状态。调用方需在流式处理逻辑中监听该字段，及时终止连接并触发重试机制。

402 错误的诊断与缓解手段

402 错误表示请求因额度或预算问题被拒绝，通常在请求到达上游服务商之前就被 OpenRouter 拦截。诊断时应首先检查响应体中的 `error.metadata` 字段，其中 `limit_source` 字段是关键线索。若其值为 `openrouter_in_flight_budget`，说明当前运行中及 recently completed 的请求已耗尽 in-flight spending budget。这是一种瞬时状态，即使当前没有活跃请求也可能发生，因为系统正在处理近期请求的结算。此时响应头中会包含 `Retry-After`，建议等待指定时间后重试。

若 `limit_source` 为 `openrouter_credits`，则表示账户余额不足以覆盖当前请求的预估费用，或单个请求的预估成本超出了 in-flight budget 的总额。前者需要充值以提升余额，后者则需降低请求规模，例如减少输入 token 数或调低 `max_tokens` 参数。若 `limit_source` 为 `openrouter_key_limit`，则说明该 API key 的独立额度已用尽，应检查 `GET /api/v1/key` 返回中的 `limit_remaining` 字段，并根据 `limit_reset` 时间等待额度重置，或提升该 key 的额度上限。

in-flight spending budget 的计算机制是：系统在请求开始时，根据输入 token 数和 `max_tokens`（若未设置则使用默认上限）预估总 token 成本，并按当前定价计算费用。该预估金额会被暂时锁定，作为“占用额度”，直到请求完成或失败后，系统在短暂的结算窗口内将占用额度替换为实际费用，随后释放。总占用额度受账户余额的一定比例限制，且有固定上限。余额低于特定阈值的账户，或新注册且无历史消费记录的账户，才会启用该机制；余额充足或有稳定消费历史的账户不受此限。免费模型请求、完全使用自有 provider key 且未启用付费插件的请求，以及企业账户、付费订阅账户、发票结算账户，均不触发 in-flight budget 检查。

缓解 402 错误的手段包括：主动调用 `GET /api/v1/key` 接口，持续监控 `limit_remaining` 和 `effective_budget.remaining_usd`，在请求量较大前预判额度状态；合理规划请求并发量，避免短时间内发起大量高成本请求；对于频繁触发 in-flight budget 的场景，可考虑分批处理任务，或在任务间隙插入延迟；若问题持续存在，应优先充值以提升余额，从而提高 in-flight budget 的上限。对于单个请求成本过高的情况，应优化 prompt 设计，减少冗余上下文，或调整 `max_tokens` 参数，使预估费用控制在预算范围内。

403 错误的来源与预算耗尽处理

403 错误在 OpenRouter 的体系中属于预算管控类问题，它与额度限制（402）不同，不直接由账户余额或单次请求的预估成本触发，而是由组织或工作区管理员预先设定的支出上限所导致。当一笔付费请求在到达上游模型服务商之前，被系统检测到其累计支出已触及某一层级的预算红线，就会立即返回 403，不会产生任何实际的模型调用开销。这种机制的目的是防止团队或项目的支出失控，属于一种事前拦截而非事后结算。

预算的检查顺序是固定的，系统会逐层比对，最先被耗尽的那一层即为拦截源。第一层是防护预算（Guardrail Budgets），它可能绑定在工作区默认配置、成员账户或具体的 API 密钥上，统计口径可以是该成员的总支出，也可以是该密钥自身的支出。第二层是工作区预算（Workspace Budgets），它针对整个工作区在某一周期内的总支出设限。第三层是密钥自身的额度限制（Key Limit），即为该密钥单独配置的周期性消费上限。每一层预算都有一个重置周期，采用 UTC 时间：每日预算在 00:00 UTC 重置，每周一在 00:00 UTC 重置，每月在第一天 00:00 UTC 重置，而终身预算则从不重置。

当请求被 403 拦截时，响应体中的 `error.metadata` 字段会明确指出拦截来源。`limit_source` 的取值可以是 `openrouter_guardrail_budget`（表示防护预算拦截）、`openrouter_workspace_budget`（工作区预算拦截）或 `openrouter_key_limit`（密钥自身额度拦截）。同时，`scope` 字段会对应 `GET /api/v1/key` 接口返回的 `budgets` 数组中的某一项，帮助开发者精确定位是哪一个具体预算条目触发了拦截。`resets_at` 字段则提供该预算窗口的下一次重置时间，格式为 ISO 8601 UTC 时间戳；对于终身预算，该字段为 `null`。需要注意的是，403 响应中通常不包含 `Retry-After` 头部，因为距离预算重置往往还有数小时甚至数天，简单地等待几秒后重试毫无意义。

要有效处理 403 错误，关键在于预防而非补救。在执行任何长时间运行的任务之前，应当先调用 `GET /api/v1/key` 接口，检查返回体中的 `effective_budget.remaining_usd` 字段。这个字段反映了当前最紧迫的预算限制及其剩余金额，是判断是否会中途触发 403 的最直接依据。如果发现剩余金额不足以支撑整个任务的预估开销，就应当提前调整任务粒度、申请更高的预算额度，或者将任务拆分为多个在不同预算周期内执行的子任务。一旦在任务执行过程中遭遇 403，根据 `limit_source` 确定具体的预算类型后，唯一的解决途径就是等待该预算窗口重置，或者由组织管理员临时提升该预算的上限。在预算重置之前，任何重试请求都会继续返回 403，因此盲目重试只会浪费客户端的请求配额。

429 错误的重试机制与流式中断应对

429 错误表示请求频率超出了系统允许的阈值，其来源分为两类：一类是 OpenRouter 平台自身的限制，另一类是上游模型服务商施加的限制。平台侧的限制主要针对免费模型变体（模型 ID 以 `:free` 结尾），根据账户累计购买的信用点数划分不同的请求频次上限。购买信用点数少于 10 的账户，每分钟最多 20 次请求，每天最多 50 次；购买信用点数达到或超过 10 的账户，每分钟仍为 20 次，但每天的上限提升至 1000 次。此外，Cloudflare 的 DDoS 防护机制也会对异常高频的请求模式进行拦截，这种拦截通常没有固定的配额，而是基于行为模式的异常检测。当请求被上游服务商限流时，`error.metadata` 中会包含 `provider_code` 字段，记录服务商返回的原始错误码，此时 OpenRouter 的回退路由机制会自动尝试调用其他可用的提供商来服务同一模型，只有在所有候选提供商均不可用时，才会将 429 错误返回给客户端。

针对 429 错误的处理，核心策略是引入指数退避的重试机制。由于限流状态是暂时的，立即重试只会加剧拥堵并可能触发更严格的拦截。客户端应当在捕获 429 响应后，解析响应头中的 `Retry-After` 字段（如果存在），获取系统建议的等待时长；若该字段不存在，则采用预设的退避算法，例如首次等待 1 秒，随后依次翻倍为 2 秒、4 秒、8 秒，同时结合随机抖动以避免多个客户端在同一时刻同时重试。对于使用免费模型变体的场景，若频繁触发 429，根本解决办法是购买至少 10 个信用点以提升每日请求上限，或者切换至该模型的付费变体，后者不受平台级请求配额的限制。若 429 来自上游服务商，则可以通过配置模型回退列表（Fallback Models），在首选模型的所有提供商均返回 429 时，自动尝试其他兼容的模型，或者放宽提供商路由偏好，增加可选服务商的范围以提高请求成功的概率。

流式传输过程中的限流处理与普通请求不同。当请求已成功建立连接并开始返回 SSE（服务器发送事件）流后，HTTP 状态码已经发送为 200，此时若触发限流，系统无法再返回 429 状态码，而是会在 SSE 事件流中插入一个特殊的错误事件。该事件的 `finish_reason` 字段会被设置为 `"error"`，并在事件负载中包含具体的错误信息和元数据。客户端需要具备解析 SSE 流的能力，在接收到 `finish_reason: "error"` 的事件时，立即终止当前流的处理，并根据错误类型决定是否重试。由于流式中断发生在数据传输中途，重试时应当从断点处重新发起请求，而不是从头开始，以避免重复传输已接收的数据。对于关键业务场景，建议在客户端实现流状态的持久化和断点续传机制，确保在遭遇流式中断后能够无缝恢复数据传输，而不丢失已积累的上下文。

AI API 额度、限流与错误处理的落地取舍

在实际接入 AI API 时，额度、限流与错误处理不是三个独立模块，而是同一套资源约束在不同维度的体现。落地取舍的核心在于：你愿意用多少成本换取多少稳定性，以及你能否承受请求失败时的延迟与数据不一致。

额度限制的本质是“你能花多少钱”，但它并不只看账户余额。平台通常会预估每个请求的 token 成本，并在请求真正完成前就占用一部分额度，这就是所谓的“在途预算”。如果你的账户余额偏低，或者属于新账户、缺乏历史消费记录，平台会启用更严格的在途预算控制。这意味着即使账户里还有余额，也可能因为多个请求同时运行、累计预估成本超过阈值而被提前拒绝。这种机制防止了“并发请求把账户刷爆”的风险，但也要求开发者必须理解：余额为正不等于请求一定能通过。应对方式是降低单次请求的 token 预估，比如减少输入长度或限制最大输出 token 数，或者主动轮询账户状态，在请求发起前确认额度充足。

限流则关注“你能在单位时间内发多少请求”。免费模型通常有严格的每分钟和每日请求上限，且这些上限与账户累计充值金额挂钩。例如，累计充值不足 10 个信用点的账户，每日免费请求上限为 50 次；达到 10 个信用点以上，上限提升至 1000 次。这种设计是为了防止滥用，但也意味着如果你的业务依赖高频调用免费模型，必须提前规划充值节奏，或者直接切换到付费模型以绕过平台级限流。此外，DDoS 防护机制会拦截异常高频的请求，这通常不是业务逻辑问题，而是流量模式被判定为攻击，需要调整请求间隔或接入更高级别的防护策略。

错误处理的关键在于区分错误来源。402 错误通常与额度或在途预算有关，403 错误与组织或密钥级别的预算上限有关，429 错误则可能来自平台限流或上游服务商的临时过载。每种错误的响应体中都会携带元数据，比如 `limit_source` 字段，明确指出是哪个层级的限制触发了拒绝。开发者应根据这个字段做分支处理，而不是依赖错误提示文本。例如，当 `limit_source` 为 `openrouter_in_flight_budget` 时，说明是并发请求占满了在途预算，此时应等待 `Retry-After` 头指定的时间后重试；如果是 `openrouter_credits`，则说明单个请求的成本超过了账户余额或预算上限，需要调整请求参数或充值。

对于流式响应，限流问题可能以更隐蔽的方式出现。如果在数据传输过程中触发限流，平台不会返回 HTTP 429，而是通过 SSE 事件发送 `finish_reason: "error"`，因为 HTTP 状态码已经在响应开始时设定为 200。这种情况下，客户端需要监听流中的错误事件，并根据错误类型决定是否重试、是否切换模型或是否暂停发送新请求。处理流式中断时，不能简单地重连并从头开始，因为这可能导致重复计费或数据重复；应记录已接收的片段，并在恢复时从断点继续，或在业务层做好幂等设计。

在落地取舍上，最现实的权衡是“主动监控 vs 被动重试”。主动调用 `GET /api/v1/key` 获取额度、预算和限流状态，虽然增加了请求开销，但能避免业务高峰时的批量失败。被动重试则依赖错误响应中的 `Retry-After` 头或指数退避策略，适合对延迟不敏感或流量波动大的场景。另一个取舍是“单一模型 vs 多模型回退”。当主模型因限流或配额耗尽不可用时，配置备用模型可以提高系统的可用性，但也会增加成本和复杂度。尤其要注意的是，备用模型的 token 价格可能高于主模型，如果回退逻辑不考虑成本，可能在“救火”的同时烧掉了更多预算。

最后，所有机制的有效性都依赖于对元数据的正确解析。平台提供的 `error.metadata` 字段包含了错误原因、限制来源、重置时间等关键信息，但这些字段的结构和语义可能随平台迭代而变化。开发者应定期审查接口文档，确保错误处理逻辑与平台最新行为一致，避免因字段变更而导致的静默失败或误判。