· reAPI Team
OpenRouterのPDFエラー:パーサーがレート制限に達したとき
ファイル取得、パーサーの制限、モデルの失敗を切り分けてOpenRouterのPDFエラーを診断します。処理経路、再試行、再利用可能なファイル注釈を比較します。

モデルを変更して同じPDFを再送しても、解析エンジンのレート制限エラーが再び返ってきます。モデルは変わりましたが、文書は依然として最初に同じパーサーを通っている可能性があります。
OpenRouterは、ファイルをネイティブにサポートするモデルへPDFを直接送信することも、そのサポートがないモデルへ内容を転送する前にPDFを解析することもできます。公開されている既定の動作では、利用可能な場合はネイティブ処理を優先し、それ以外ではMistral OCRを使用します。[1] そのため、モデル名を2つ変更しても、先行する解析手順は変わらないことがあります。同じエラーに対してもう一度試す前に、その処理経路を特定してください。
この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の3つのエンジンが記載されています。ネイティブ処理では、ファイルを対応モデルに転送します。Mistral OCRは文書の内容を抽出し、Cloudflare AIはPDFをMarkdownに変換します。[1]
文章、財務表、グラフが含まれる架空のレポートを考えると、経路は質問に応じて選ぶ必要があります。文章の要約にはテキスト変換で十分かもしれません。グラフのラベルについて質問するなら、そのラベルが保持され、モデルから参照できる必要があります。回答を返す経路であっても、その質問に必要な証拠が保持されているとは限りません。
同じOCR経路を必要とする2つのモデル間で切り替えても、パーサーエラーは残ることがあります。ネイティブPDF対応モデルを選び、その経路を使えば、文書処理の経路も変わります。モデルファミリー名から対応状況を推測せず、正確なモデルの入力制限と適合性を確認してください。
古い例ではpdf-textが使われている場合があります。OpenRouterの現行ガイドでは、このエンジンは非推奨とされ、cloudflare-aiへリダイレクトされます。[1] ラベルを更新すると意図した経路が分かりやすくなりますが、それだけで変換品質や処理能力が向上したことにはなりません。
BYOKを使ってもOCR段階の料金はなくなりません。OpenRouterによると、この処理ではOpenRouter自身のMistralキーを使い、推論に個人のプロバイダーキーを使う場合でも、OCR料金はOpenRouterアカウントに請求されます。[1] 別のモデル認証情報を使っているからといって、独立したパーサー割り当てを得た証拠にはなりません。
もう一度解析する前に、すでにある結果を確認する
有用な復旧ケースは、パーサーの処理が完了した後に始まります。架空のレポートは解析されたものの、試したすべての推論プロバイダーが補完結果を生成できなかったとします。Chat Completionsでは、エラーに解析済みファイルの注釈がerror.metadata.file_annotationsの下に残ることがあるとOpenRouterは説明しています。[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やワークフローがすでに再試行しているか確認してください。再試行するヘルパー関数の外側にループを追加すると、実際の試行回数が外側のカウンター表示を超えることがあります。待機時間も含めて文書ごとの試行記録を1つにまとめ、まだ制約されている手順にバッチが繰り返し戻らないようにしてください。
バッチでは、文書ごとに進捗を保持してください。9件のレポートがすでに完了し、10件目が延期されたときに10件すべてを再起動すると、役立つ違いが失われます。完了したレポート、解析済みだが回答がないレポート、解析待ちの文書を別々の状態で管理してください。これはアプリケーションのスケジューリングに関する提案であり、OpenRouterがバッチをそのように管理するという主張ではありません。
自分で制御できるワーカーを調整してください。各ワーカーが少数のリクエストしか送らなくても、複数のワーカーが同じ経路に送信すれば、合計で大きなバーストになることがあります。共有キューを使うと、全体の負荷を把握できます。追加のキーやアカウントによって、OpenRouterが全体で管理する処理容量を増やせるとは、ドキュメントに記載されていません。[4]
置き換えた経路で何が保持されたかを確認する
レポートの回答を採用する前に、選択した経路が提供した情報を調べてください。連続したテキストの要約と、すべてのグラフを比較することでは、必要な情報が異なります。前者が成功しても、後者には重要な画像が欠けていることがあります。
Mistral OCRについて、OpenRouterはPDFごとに最大8枚の画像を要求でき、下流の1回のリクエストに転送される画像も最大8枚だと説明しています。超過した画像は破棄され、抽出済みのテキストは保持されます。下流モデルが画像を受け付けられない場合は、解析済みテキストのみが転送されます。[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日に取得。モデルのトークン料金と補助料金の違いを確認するため、11月16日にポリシー全文を確認。
- reAPI。*Claude Sonnet 5.5 API リファレンス:入力形式。*2026年11月17日確認。Claude Sonnet 5.5。