Hermes Agent 上 OpenRouter 限流错误处理指南

你的智能体在对话中途停下了

你和 Hermes Agent 终于聊到第三轮有价值的内容,回复却空白返回,日志里跳出一行红字:429 Too Many Requests。或者更糟,一个 402 Payment Required,模型直接拒绝了请求。一小时前还运行顺畅的智能体,现在满屏都是重试报错,你离换服务商只差一次调试会话。

只要弄清每个错误的含义,OpenRouter 的错误码其实非常精准。429 是限流,来源有三处。402 是余额耗尽,行为与 429 毫无相似。503 是上游服务商不可用,是唯一可以无痛自动化处理的类型。每种错误都有对应的修复方法,而 Hermes Agent 的 models 数组能让大多数问题变成小事。

一眼看懂 OpenRouter 错误码

在动配置之前,先弄清 API 到底在告诉你什么。OpenRouter 明确记录了这些错误码,数字本身很重要。

429 和 402 在终端里看起来很像,但需要相反的处理方式。对 402 死循环重试只会烧光你的重试预算,余额依然是零。而对 429 做有节制的重试,才是关键所在。

另一个值得留意的细节是 error.metadata.provider_code。当一个 429 来自处理你请求的上游服务商(Anthropic、DeepSeek、OpenAI、Groq),OpenRouter 会把该服务商的原始错误码放到这个字段里。这样就能区分是 OpenRouter 平台侧的限制,还是上游租户侧的限制,两者的解法完全不同。

成因一:OpenRouter 免费额度的每日封顶

症状:昨天正常,今早也正常,可现在几乎没什么流量,每个请求却都返回 429。通常在一次正常的 Hermes 会话进行约 20 分钟后出现。

原因:OpenRouter 免费额度对免费模型允许每分钟 20 次请求,每日封顶 50 次。一次性充值 10 美元后,每日下限会永久从 50 提升到 1000。Hermes Agent 密集的工具调用循环(每一轮就是一次 API 调用,还有重试),在一次中等长度的对话中就会把 50 次的日额度耗光。

**先检查:**确认你配置中的模型是否属于免费额度。OpenRouter 上的免费模型 slug 会带 :free 后缀,例如 deepseek/deepseek-v4-flash:free。如果你的 model: 行以 :free 结尾,就落在这个封顶里。

**立刻解决:**在 OpenRouter 控制台里充值 10 美元。每日封顶永久提升到 1000/天,足够一位正常的 Hermes 用户使用。

**根本解决:**别再把生产流量走免费模型。免费模型是用于评估,不是用来跑一个正在服务的智能体。换成去掉 :free 的同款模型,按牌价付费(去掉后缀的 DeepSeek V4-Flash 价格是 0.14 美元/百万 input,一天 Hermes 使用只是个位数美分)。完整的价格账在Hermes Agent 最便宜的 OpenRouter 模型一文里。

成因二:上游服务商限流(带 provider_code 的 429)

症状:你用的是付费模型,余额也充足,但 Hermes 一忙起来仍然会撞到 429。响应体里的 error.metadata.provider_code 带有 rate_limit_exceeded 或 insufficient_quota 之类的值。

原因:OpenRouter 本身不会对付费模型设硬性上限,但上游服务商会。Anthropic、OpenAI 和 DeepSeek 都会根据你的租户等级设置账户级限流。当 OpenRouter 把你的请求路由到上游时,上游拒绝了,OpenRouter 就把这个拒绝原样以 429 返回。

排查:

• 读 error.metadata.provider_code。如果显示 rate_limit_exceeded,就是这种情况。
• 判断请求是发生在突发状态(短时间内几十轮)还是稳态。突发会撞每分钟限制,持续流量会撞每日限制。
• 确认模型。有些模型只走单一服务商,配额较紧(通过 OpenRouter 使用 Anthropic 品牌模型时,会共享 Anthropic 自家账户的限流)。

解决方法:

• 遵循响应中的 Retry-After 头。无论是 429 还是 503,OpenRouter 都会返回一个以秒为单位的 Retry-After。先按这个秒数等待再重试,如果还失败,再用带抖动的指数退避。
• 配置一条回退模型链(见下文成因四)。这里最有效的解法就是模型数组,Hermes 会自动用下一个模型重试,而不是让这一轮失败。
• 如果某个模型一直出问题,考虑 BYOK。把自己的 Anthropic 或 OpenAI 密钥接入 OpenRouter,你享受的是自己上游账户的额度,而不是与其他人共享 OpenRouter 的池子。

成因三:对话中途余额用尽(402)

症状:智能体撑过了前 30 轮,之后每次请求都返回 402 insufficient_credits。OpenRouter 控制台显示余额为 0.00 美元。

原因:OpenRouter 是预付余额,不是月度账单。一旦余额归零,每个请求都会被 402 拒绝,直到你充值。免费模型用户在当日免费额度用尽时也会看到 402(与付费余额耗尽共用同一个错误码,虽然容易混淆,但与 OpenRouter 文档一致)。

解决方法:

• 在 OpenRouter 控制台开启自动充值。设置一个阈值,比如余额低于 2 美元时自动补 10 美元。这是唯一能在生产中避免 402 的措施。
• 在同一个控制台设置每月支出上限,防止自动充值悄悄扩张成糟糕的一个月。
• 如果你在 Hermify 的 Starter 层使用 BYOK,OpenRouter 密钥属于你,余额也由你自己充值。Hermify 不会代垫。

不要对 402 做客户端重试。每次重试就是又一次返回 402 的 API 调用,而 OpenRouter 会把这些失败请求计入你的限流额度。

成因四:没有配置回退链

症状:OpenRouter 服务商网络中任何一个模型出现故障,都会把你的智能体彻底打下线,直到上游恢复为止。主模型上的一次 429 就会导致会话中断。

原因:默认情况下,Hermes Agent 每次发出的请求只会指定一个模型。如果这个模型被限流,或者它的所有服务商都满负荷,OpenRouter 会返回错误,而 Hermes 没有别的路可走。你会看到一条红色日志,这一轮就丢了。

解决方法是 OpenRouter 的 models 参数,它接受一个按优先级排序的模型数组。如果第一个模型报错,OpenRouter 会依次尝试下一个,再下一个。只有当最后一个也失败,错误才会返回给 Hermes。

**在 ~/.hermes/config.yaml 中配置一条三级回退链。**一个生产形态的示例:

provider: openrouter
openrouter_api_key: sk-or-你的密钥
model: deepseek/deepseek-v4-pro
fallback_models:
  - anthropic/claude-haiku-4-5
  - google/gemini-2.5-flash
  - openai/gpt-4.1-mini

这条链给你一个强主力(DeepSeek V4-Pro,擅长工具密集型推理)、一个来自不同服务商体系的快速可靠副选,以及分布在不同云上的两个后备。如果 DeepSeek 出问题,请求会切到 Anthropic,不会丢掉这一轮。Hermes Agent 最佳模型服务商一文更深入地讨论了不同服务商体系之间的取舍。

配置回退链时的经验:

• 选择来自不同服务商体系的模型。OpenAI 出故障时,两个 OpenAI 模型会一起挂。
• 优先按质量排序,再看成本。链条自上而下执行,遇到第一个成功就停止。
• 控制在 3 到 5 个条目之间。十个回退意味着在糟糕的日子里要串行重试十次,比一次直接失败更糟。

成因五:Hermes 自身触发的重试风暴

症状:一次 429 在日志里演变成成百上千次失败请求,每一次都让限流雪上加霜。控制台恰好在系统崩溃的时间点出现请求峰值。

原因:如果没有指数退避,Hermes 会立刻重试一个被限流的请求,又再次触发同一个限流,然后再次重试。重试循环把一个原本可恢复的错误变成了自作自受的宕机。这是 OpenRouter 版本的经典客户端限流踩踏。

解决方法:

• 确认 Hermes 是否遵循 Retry-After。较新的版本默认会遵循;某些老的分叉可能不会。用 hermes --version 查看版本,如果落后就升级。
• 如果你用单租户账户跑 Hermes,配置一个令牌桶队列。强制请求间至少间隔 3 秒,可以在单用户场景下彻底消除 429。
• 如果重试循环已经发生,先等 5 分钟再重启智能体。OpenRouter 的限流器有一个冷却窗口,立即重启会延长封禁时间。

同样的失败模式会出现在任何高并发的 API 集成里,不只是 OpenRouter。日志约定与诊断方法参见Hermes Agent 调试与可观测性。

何时该停止照看服务商

本文里的每一条修复,都是对模型层布线的小幅修正。models 数组加上 OpenRouter 的自动充值,能覆盖 90% 会出问题的场景。剩下的靠耐心和对 Retry-After 的正确处理。

真正吃时间的,是在智能体项目做到一半突然罢工的那个下午,你才发现免费额度触顶、回退链从未配置、重试循环把一个小抽风演变成两小时的宕机。如果你不想以硬碰硬的方式学会 OpenRouter 的错误分类学,Hermify 在 Telegram 上运行托管的 Hermes Agent,回退链已经预先接好,OpenRouter 密钥可按量使用(自带或使用我们的),自动充值下限确保你不会归零。你的 BYOK 密钥仍然属于你,只是不再由你来值班处理 429。

使用 Hermify 开始,跳过重试风暴的事后复盘。

Sources

• OpenRouter API credit and rate limits
• OpenRouter model fallbacks documentation
• OpenRouter reliability and failover explainer
• OpenRouter free tier 2026 breakdown
• Handling OpenRouter 429 with retry strategies