· reAPI Team
OpenRouter PDF errors: when the parser is rate limited
Diagnose OpenRouter PDF errors by separating file retrieval, parser limits and model failures. Compare processing routes, retries and reusable file annotations.

You change the model, send the same PDF again, and receive another parsing-engine rate-limit error. The model changed, but the document may still be going through the same parser first.
OpenRouter can send a PDF directly to a model with native file support or parse it before forwarding the content to a model without that support. Its documented default prefers native processing where available and otherwise uses Mistral OCR.[1] Two different model names can therefore leave the earlier parsing step unchanged. Identify that route before spending another attempt on the same error.
Find where this PDF stopped
Save the full response with its status, request ID, selected model, endpoint and engine. Keep the engine's default or explicit setting in the record; do not describe an unspecified route as though you had selected it deliberately.
The input shape depends on the API. Responses uses an input_file content item with file_url or file_data. Chat Completions uses a file content part.[1] A request copied between endpoints without adapting that shape can fail before parser capacity matters.
Next check file delivery. Opening a PDF in your signed-in browser does not show that the service can retrieve the same URL without that login. OpenRouter documents public URLs for direct retrieval and base64 input for local or private documents.[1] Use the appropriate permitted method; making a confidential document public is not a necessary troubleshooting step.
If the error names the parsing engine, retain that wording. If it instead says the file could not be retrieved, fix delivery first. If parsing completed but inference failed, preserve the parsed content before repeating the whole operation. These cases can all produce an application's generic “PDF failed” message, but they leave different work to do.
Read the body or stream as well as the HTTP status. OpenRouter documents errors that arrive after headers have already been sent, including failures inside a response that began with a successful status.[2] An HTTP logger that records only 200 can miss the failure your application needs to handle.
A model switch only helps if it changes the relevant route
The PDF guide lists three engines: native, mistral-ocr and cloudflare-ai. Native processing forwards the file to a supporting model. Mistral OCR extracts document content, while Cloudflare AI converts the PDF to Markdown.[1]
For a hypothetical report with narrative text, a financial table and a chart, the choice should follow the question. A text conversion may be enough to summarize the narrative. A question about the chart's labels needs those labels preserved and available to the model. A route that returns an answer has not necessarily preserved the evidence required for that question.
If you switch between two models that both need the same OCR route, the parser error can remain. If you select a model with native PDF support and use that route, you have changed the document-processing path too. Check the exact model's input limits and suitability rather than inferring support from a family name.
Older examples may use pdf-text. OpenRouter's current guide marks that engine as deprecated and redirects it to cloudflare-ai.[1] Updating the label makes the intended route clearer, but does not by itself prove that conversion quality or capacity improved.
BYOK does not remove the OCR stage's fee. OpenRouter says it uses its own Mistral key for that work and charges OCR to the OpenRouter account even when inference uses a personal provider key.[1] A different model credential is not evidence that you now have an independent parser allocation.
Before parsing again, look for the result you already have
A useful recovery case begins after the parser finishes. Suppose the hypothetical report was parsed, then every attempted inference provider failed to produce a completion. In Chat Completions, OpenRouter documents that the error can still contain the parsed file annotations under error.metadata.file_annotations.[1]
That means the failed response may contain useful completed work. Read both the normal assistant-message annotations and the documented error location before discarding it:
| Place in the response | What to look for |
|---|---|
| Chat Completions assistant message | Reusable file annotations containing parsed content and a file hash |
Chat Completions error.metadata.file_annotations | The same parsed-file annotation shape after parsing succeeded but inference providers failed |
| Responses output annotations | file_citation references, which cannot be returned to skip parsing |
These distinctions come from OpenRouter's PDF guide.[1] A citation pointing to a document is not the same object as a reusable parsed document.
Keep the full reusable annotation with the document it describes, then follow the guide's Chat Completions reuse format for a subsequent permitted request. The annotation's parsed content and hash are what allow re-parsing to be skipped. Copying only the filename or the answer's citation does not supply that content.
If you collect annotations from both successful and error responses, the documented identity for deduplication is file.hash. Preserve the association with the original document in your application. In the report example, accidentally attaching annotations from a different quarterly report could produce an apparently coherent answer to the wrong evidence.
This path applies to parsed routes. Native processing forwards the PDF directly and does not produce these parser annotations. Nor can annotation reuse rescue an attempt that never completed parsing.[1] If there is no usable parsed result, keep the document pending and address the failed stage instead of manufacturing an annotation.
Stored annotations can contain extracted text and images. Treat them as copies of document content with appropriate access and retention controls, not as harmless diagnostic metadata. The file retention guide addresses tracking those copies. Avoid putting a full confidential annotation into a general-purpose error log.
Keep the document version with the saved parsing result. If someone replaces the report while retaining its filename, yesterday's extracted content does not establish what today's file contains. Before reuse, verify that the saved content belongs to the version being questioned; a familiar filename alone is an inadequate match.
Defer the document without restarting the whole batch
When the response identifies throttling, inspect its retry guidance. OpenRouter says a Retry-After may accompany relevant rate-limit or availability responses.[2] The HTTP header can be a delay in seconds or an HTTP date; a numeric value is not milliseconds.[3]
Apply a valid returned delay before another permitted attempt. If it falls beyond the document job's deadline, defer the job visibly rather than keeping a hidden retry loop running. Where no usable hint is present, follow the provider's documented handling and bound both attempts and total elapsed time.
Check whether the SDK or workflow already retries. An outer loop around a retrying helper can produce more attempts than the number shown by the outer counter. Keep one record of the document's attempts, including waits, so the batch does not repeatedly return to a step that is still constrained.
For a batch, preserve progress per document. If nine reports already completed and the tenth is deferred, restarting all ten throws away the useful distinction. Keep completed reports, parsed-but-unanswered reports and documents still waiting for parsing in separate states. This is an application scheduling recommendation, not a claim that OpenRouter manages your batch that way.
Coordinate the workers you control. Several workers each sending a small number of requests can still create a large combined burst at the same route. A shared queue makes the aggregate workload visible. Additional keys or accounts are not a documented way to create more of OpenRouter's globally governed capacity.[4]
Check what the replacement route kept
Before accepting the report's answer, inspect the information the chosen route supplied. A continuous text summary and a comparison of every chart have different requirements. The first can succeed even when the second lacks critical images.
For Mistral OCR, OpenRouter documents requesting at most eight images per PDF and forwarding no more than eight per downstream request. Surplus images are dropped while extracted text is retained. If the downstream model cannot accept images, only the parsed text is forwarded.[1]
Consequently, an answer about an omitted image cannot be trusted merely because the request succeeded. Check whether the relevant visual evidence was present. If you choose to extract text yourself and send that to inference, inspect table structure, page mapping and any information lost from scans or diagrams. That is your own extraction workflow, not another named OpenRouter engine.
Separate the wait from the work already charged
For a slow PDF request, elapsed time can include file retrieval, parsing, model processing and waits between retries. Use the intervals actually visible in your trace. Switching an inference model cannot be assumed to remove time spent waiting for the parser or sitting in your own queue.
There is no single useful “OpenRouter latency” number for all these routes. Keep the document's characteristics, engine, model and concurrency with any measured duration. This guide has not run a latency benchmark and does not assign an expected completion time. A timestamp showing when the client stopped waiting is not the same as a measurement of each remote stage.
Billing also follows the work. Native input is charged under the model's input pricing. OCR has separate charges. Cloudflare conversion is documented as free processing, which does not make the following model inference free.[1]
OpenRouter's zero-completion protection distinguishes qualifying model-token charges from auxiliary work already performed. Parsing or OCR can still be billed when a later answer fails, depending on the actual work and failure case.[5] Inspect that charge breakdown before calling the whole attempt free or charging it twice in your own estimate.
Return to the report's last completed step. If the file was never retrieved, fix the input. If parsing is deferred, keep its place in the queue. If reusable parsed content exists, preserve it for the next appropriate inference attempt. That recovery choice follows the document you actually have, rather than another model name selected in the hope of bypassing an unchanged parser.
If you evaluate reAPI for document input
On reAPI, document input follows each model's documented native format. Media, including PDF files, must be sent as public HTTP(S) URLs; base64 and data: URIs are not accepted.[6] Support is model-specific: the Claude Sonnet 5.5 reference, for example, states that PDF input has not yet been verified. Check the model's page before moving a PDF workflow, and keep the rate-limit handling above for whichever service processes the file.
References
- OpenRouter, “PDF Inputs,” official documentation. Read in full November 16, 2026; engine, API format, OCR images and annotation sections.
- OpenRouter, “Errors and Debugging,” official documentation, error envelope, error codes and Retry-After sections. Retrieved November 15, 2026; relevant sections reviewed November 16.
- MDN, Retry-After header. Read November 16, 2026.
- OpenRouter, “Limits,” official documentation, introduction and rate-limit handling sections. Read November 16, 2026.
- OpenRouter, “Zero Completion Insurance,” official documentation. Retrieved November 15, 2026; full policy reviewed November 16 for model-token and auxiliary-charge distinctions.
- reAPI. Claude Sonnet 5.5 API reference: input formats. Reviewed November 17, 2026. Claude Sonnet 5.5.