· reAPI Team
OpenRouter PDF 错误:解析器触发速率限制时怎么办
通过区分文件获取、解析器限制和模型故障来诊断 OpenRouter PDF 错误。比较处理路径、重试方式和可复用的文件注释。

你更换了模型,再次发送同一份 PDF,却又收到解析引擎速率限制错误。模型变了,但文档可能仍然先经过同一个解析器。
OpenRouter 可以将 PDF 直接发送给原生支持文件的模型,也可以先解析 PDF,再把内容转发给不支持文件的模型。其文档说明,默认情况下会优先使用可用的原生处理方式,否则使用 Mistral OCR。[1] 因此,两个不同的模型名称仍可能让前面的解析步骤保持不变。再为同一个错误尝试一次之前,先确认这条处理路径。
找出 PDF 卡在哪一步
保存完整响应及其状态、请求 ID、所选模型、端点和引擎。记录引擎是默认设置还是显式设置;不要把未指定的路径描述成你有意选择的路径。
输入格式取决于 API。Responses 使用带有 file_url 或 file_data 的 input_file 内容项。Chat Completions 使用 file 内容部分。[1] 将请求从一个端点复制到另一个端点却不调整格式,可能会在解析器容量成为问题之前就导致失败。
接下来检查文件传递。你在已登录的浏览器中能打开 PDF,并不能证明服务无需该登录即可获取同一个 URL。OpenRouter 文档说明,直接获取应使用公开 URL,本地或私有文档则应使用 base64 输入。[1] 使用适当且获准的方法;排查问题并不要求将机密文档公开。
如果错误指出了解析引擎,请保留该措辞。如果错误说无法获取文件,就先修复文件传递。如果解析已经完成但推理失败,请在重试整个操作前保留已解析的内容。这些情况都可能让应用只显示笼统的“PDF 处理失败”,但后续需要处理的工作各不相同。
除了 HTTP 状态,也要读取响应正文或流。OpenRouter 文档指出,错误可能在响应头已发送后才到达,包括出现在以成功状态开始的响应中。[2] 只记录 200 的 HTTP 日志记录器可能会漏掉应用需要处理的故障。
只有切换模型改变了相关路径,才会有帮助
PDF 指南列出了三种引擎:native、mistral-ocr 和 cloudflare-ai。原生处理会将文件转发给支持该功能的模型。Mistral OCR 会提取文档内容,而 Cloudflare AI 会将 PDF 转换为 Markdown。[1]
假设有一份报告,包含叙述性文字、财务表格和图表,选择应取决于问题。文本转换可能足以概述叙述内容。若问题涉及图表标签,就需要保留这些标签并让模型能够获取。某条路径能返回答案,并不代表它一定保留了回答该问题所需的证据。
如果你在两个都需要同一条 OCR 路径的模型之间切换,解析器错误可能依然存在。如果你选择支持原生 PDF 的模型并使用该路径,就同时改变了文档处理流程。应检查确切型号的输入限制和适用性,而不要根据型号系列名称推断其支持情况。
较旧的示例可能使用 pdf-text。OpenRouter 当前指南将该引擎标记为已弃用,并将其重定向到 cloudflare-ai。[1] 更新标签可以让预期路径更清楚,但仅此并不能证明转换质量或处理能力有所提升。
BYOK 不会免除 OCR 阶段的费用。OpenRouter 表示,这项工作使用其自己的 Mistral 密钥;即使推理使用个人提供商密钥,OCR 费用仍会计入 OpenRouter 账户。[1] 使用不同的模型凭据,并不能证明你现在有独立的解析器配额。
再次解析前,先检查是否已有结果
一种有用的恢复场景是解析器已完成工作之后。假设这份虚构报告已经解析,但每个尝试过的推理提供商都未能生成补全结果。在 Chat Completions 中,OpenRouter 文档说明,错误仍可能在 error.metadata.file_annotations 下包含已解析文件的注释。[1]
这意味着失败的响应可能包含已经完成且有用的工作。丢弃响应前,应同时读取常规 assistant 消息注释和文档记录的错误位置:
| 响应中的位置 | 要查找的内容 |
|---|---|
| Chat Completions assistant 消息 | 可复用的 file 注释,其中包含已解析内容和文件哈希 |
Chat Completions error.metadata.file_annotations | 解析成功但推理提供商失败后,相同形态的已解析文件注释 |
| Responses 输出注释 | file_citation 引用,不能用于跳过解析 |
这些区别来自 OpenRouter 的 PDF 指南。[1] 指向某份文档的引用与可复用的已解析文档不是同一种对象。
将完整的可复用注释与其描述的文档一并保存,然后按照指南中的 Chat Completions 复用格式提交后续获准的请求。注释中的已解析内容和哈希可以跳过重新解析。只复制文件名或答案引用并不能提供这些内容。
如果你从成功响应和错误响应中收集注释,文档指定用于去重的标识是 file.hash。在应用中保留注释与原始文档之间的关联。在报告示例中,若意外附上另一份季度报告的注释,可能会得到看似连贯、实际却依据了错误证据的答案。
这条路径适用于已解析的处理方式。原生处理会直接转发 PDF,不会生成这些解析器注释。注释复用也无法挽救从未完成解析的尝试。[1] 如果没有可用的解析结果,就让文档保持待处理状态,并处理失败的阶段,而不是伪造注释。
保存的注释可能包含提取出的文本和图像。应将它们视作文档内容的副本,并设置适当的访问和保留控制,而不是无害的诊断元数据。文件保留指南介绍了如何跟踪这些副本。避免将完整的机密注释放入通用错误日志。
将文档版本与保存的解析结果一并保留。如果有人替换了报告却沿用原文件名,昨天提取的内容并不能证明今天的文件包含什么。复用前,请确认已保存的内容属于当前要查询的版本;仅凭熟悉的文件名并不足以匹配。
延后处理文档,而不必重启整个批次
当响应指出请求受到限制时,请检查其中的重试提示。OpenRouter 表示,相关的速率限制或可用性响应可能会带有 Retry-After。[2] HTTP 标头中的值可以是秒数,也可以是 HTTP 日期;数字值不是毫秒。[3]
在再次进行获准的尝试前,等待有效的返回延迟。如果等待时间超过文档任务的截止时间,就应明确延后该任务,而不是让隐藏的重试循环持续运行。若没有可用提示,请遵循提供商文档中的处理方式,并限制尝试次数和总耗时。
检查 SDK 或工作流是否已经在重试。若在自动重试的辅助函数外再套一层循环,实际尝试次数可能会超过外层计数器显示的次数。记录文档的所有尝试及等待时间,避免批次反复返回仍受限制的步骤。
对于批次,要按文档保留进度。如果九份报告已经完成,第十份被延后,重启全部十份就会抹掉这一重要区别。应将已完成的报告、已解析但未获回答的报告,以及仍在等待解析的文档分别记录为不同状态。这是应用调度方面的建议,并不表示 OpenRouter 会以这种方式管理你的批次。
协调你能控制的工作进程。多个工作进程各自只发送少量请求,汇总后仍可能在同一路径形成大量突发请求。共享队列可以让整体工作负载一目了然。OpenRouter 的文档没有说明增加密钥或账户可以扩大其全局管理的容量。[4]
检查替代路径保留了什么
接受报告中的答案之前,请检查所选路径提供的信息。连续文本摘要和比较每张图表的要求并不相同。即使前者成功,后者仍可能缺少关键图像。
对于 Mistral OCR,OpenRouter 文档说明,每份 PDF 最多请求八张图像,并且每个下游请求最多转发八张。超出的图像会被丢弃,同时保留提取的文本。如果下游模型无法接受图像,则只会转发已解析文本。[1]
因此,不能仅仅因为请求成功,就信任关于已省略图像的答案。请检查相关视觉证据是否存在。如果你选择自行提取文本并将其发送给推理模型,请检查表格结构、页面映射,以及扫描件或图表中丢失的任何信息。这是你自己的提取工作流,不是另一个名为 OpenRouter 引擎的选项。
区分等待时间和已经计费的工作
对于处理较慢的 PDF 请求,耗时可能包括文件获取、解析、模型处理以及重试间隔中的等待。使用跟踪记录中实际可见的时间段。不能假定切换推理模型会消除等待解析器或在你自己的队列中排队所花的时间。
这些路径没有一个通用且有用的“OpenRouter 延迟”数字。测量耗时时应记录文档特征、引擎、模型和并发情况。本指南没有运行延迟基准测试,也没有给出预期完成时间。客户端停止等待的时间戳不等于对各个远程阶段的测量。
计费也取决于实际处理。原生输入按模型的输入价格计费。OCR 有单独费用。文档说明 Cloudflare 转换免费,但这不代表后续模型推理也免费。[1]
OpenRouter 的零补全保护会区分符合条件的模型令牌费用与已经完成的辅助工作费用。如果后续答案失败,解析或 OCR 仍可能收费,具体取决于实际工作和故障情况。[5] 在认定整个尝试免费或在自己的估算中将费用重复计算前,请查看费用明细。
回到报告最后完成的步骤。如果文件从未被获取,就修复输入。如果解析被延后,就让文档留在队列中。如果已有可复用的解析内容,就为下一次合适的推理尝试保留它。这样的恢复选择依据的是你实际拥有的文档状态,而不是寄希望于另一个模型名称绕过未改变的解析器。
如果你在评估用 reAPI 处理文档输入
在 reAPI 上,文档输入遵循各模型文档中说明的原生格式。包括 PDF 在内的媒体必须以公网 HTTP(S) URL 发送,不接受 base64 和 data: URI。[6] 支持情况因模型而异:例如,Claude Sonnet 5.5 的参考文档写明 PDF 输入尚未验证。迁移 PDF 工作流之前,请先查看该模型的页面;无论由哪个服务处理文件,都继续保留上文的限流处理。
参考资料
- OpenRouter,“PDF Inputs”,官方文档。2026 年 11 月 16 日通读;涉及引擎、API 格式、OCR 图像和注释的章节。
- OpenRouter,“Errors and Debugging”,官方文档,错误封装、错误代码和 Retry-After 章节。2026 年 11 月 15 日检索;相关章节于 11 月 16 日查阅。
- MDN,Retry-After header。2026 年 11 月 16 日查阅。
- OpenRouter,“Limits”,官方文档,简介和速率限制处理章节。2026 年 11 月 16 日查阅。
- OpenRouter,“Zero Completion Insurance”,官方文档。2026 年 11 月 15 日检索;2026 年 11 月 16 日通读政策,核对模型令牌与辅助费用的区别。
- reAPI。*Claude Sonnet 5.5 API 参考:输入格式。*审阅于 2026 年 11 月 17 日。Claude Sonnet 5.5。