GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Alle Anleitungen

· reAPI Team

OpenRouter-PDF-Fehler: Wenn der Parser das Ratenlimit erreicht

Diagnostiziere OpenRouter-PDF-Fehler, indem du Dateiabruf, Parserlimits und Modellfehler unterscheidest. Vergleiche Verarbeitungswege, Wiederholungen und wiederverwendbare Dateianmerkungen.

OpenRouter-PDF-Fehler: Wenn der Parser das Ratenlimit erreicht

Du wechselst das Modell, sendest dieselbe PDF erneut und erhältst wieder einen Fehler wegen des Ratenlimits der Parsing-Engine. Das Modell hat sich geändert, aber das Dokument läuft möglicherweise weiterhin zuerst durch denselben Parser.

OpenRouter kann eine PDF direkt an ein Modell mit nativer Dateiunterstützung senden oder sie parsen, bevor der Inhalt an ein Modell ohne diese Unterstützung weitergeleitet wird. Laut dokumentierter Standardeinstellung wird, sofern verfügbar, die native Verarbeitung bevorzugt; andernfalls wird Mistral OCR verwendet.[1] Zwei verschiedene Modellnamen können daher den vorherigen Parsing-Schritt unverändert lassen. Ermittle diesen Verarbeitungsweg, bevor du wegen desselben Fehlers einen weiteren Versuch unternimmst.

Finde heraus, an welcher Stelle diese PDF angehalten hat

Speichere die vollständige Antwort mit Status, Request-ID, ausgewähltem Modell, Endpunkt und Engine. Halte fest, ob die Einstellung der Engine standardmäßig oder ausdrücklich gesetzt war; beschreibe einen nicht angegebenen Weg nicht so, als hättest du ihn bewusst ausgewählt.

Das Eingabeformat hängt von der API ab. Responses verwendet ein Inhaltselement input_file mit file_url oder file_data. Chat Completions verwendet einen Inhaltsteil file.[1] Wird eine Anfrage zwischen Endpunkten kopiert, ohne dieses Format anzupassen, kann sie scheitern, bevor die Parserkapazität eine Rolle spielt.

Prüfe als Nächstes die Dateibereitstellung. Dass du eine PDF in deinem angemeldeten Browser öffnen kannst, zeigt nicht, dass der Dienst dieselbe URL ohne diese Anmeldung abrufen kann. OpenRouter dokumentiert öffentliche URLs für den direkten Abruf und base64-Eingaben für lokale oder private Dokumente.[1] Verwende die geeignete und zulässige Methode; ein vertrauliches Dokument öffentlich zu machen, ist zur Fehlersuche nicht erforderlich.

Wenn der Fehler die Parsing-Engine nennt, behalte diesen Wortlaut bei. Wenn stattdessen angegeben wird, dass die Datei nicht abgerufen werden konnte, behebe zuerst die Bereitstellung. Wenn das Parsing abgeschlossen wurde, aber die Inferenz fehlschlug, bewahre den geparsten Inhalt auf, bevor du den gesamten Vorgang wiederholst. Alle diese Fälle können in einer Anwendung als allgemeine Meldung „PDF fehlgeschlagen“ erscheinen, erfordern aber unterschiedliche weitere Schritte.

Lies neben dem HTTP-Status auch den Body oder Stream. OpenRouter dokumentiert Fehler, die eintreffen, nachdem die Header bereits gesendet wurden, darunter Fehler innerhalb einer Antwort, die mit einem Erfolgsstatus begonnen hat.[2] Ein HTTP-Logger, der nur 200 aufzeichnet, kann den Fehler übersehen, den deine Anwendung behandeln muss.

Ein Modellwechsel hilft nur, wenn er den relevanten Verarbeitungsweg ändert

Der PDF-Leitfaden führt drei Engines auf: native, mistral-ocr und cloudflare-ai. Bei der nativen Verarbeitung wird die Datei an ein unterstütztes Modell weitergeleitet. Mistral OCR extrahiert den Dokumentinhalt, während Cloudflare AI die PDF in Markdown umwandelt.[1]

Bei einem hypothetischen Bericht mit Fließtext, einer Finanztabelle und einem Diagramm sollte sich die Auswahl nach der Frage richten. Eine Textumwandlung kann ausreichen, um den Fließtext zusammenzufassen. Bei einer Frage zu den Beschriftungen des Diagramms müssen diese Beschriftungen erhalten bleiben und dem Modell zur Verfügung stehen. Ein Verarbeitungsweg, der eine Antwort liefert, hat nicht unbedingt die für diese Frage benötigten Belege erhalten.

Wenn du zwischen zwei Modellen wechselst, die beide denselben OCR-Weg benötigen, kann der Parserfehler bestehen bleiben. Wenn du ein Modell mit nativer PDF-Unterstützung auswählst und diesen Weg verwendest, änderst du auch den Dokumentverarbeitungsweg. Prüfe die Eingabelimits und Eignung des genauen Modells, statt die Unterstützung aus einem Familiennamen abzuleiten.

Ältere Beispiele verwenden möglicherweise pdf-text. Im aktuellen Leitfaden von OpenRouter ist diese Engine als veraltet gekennzeichnet und wird zu cloudflare-ai weitergeleitet.[1] Wenn du die Bezeichnung aktualisierst, wird der beabsichtigte Weg klarer; das allein beweist jedoch weder eine bessere Konvertierungsqualität noch höhere Kapazität.

BYOK hebt die Gebühr für die OCR-Phase nicht auf. OpenRouter gibt an, für diese Arbeit einen eigenen Mistral-Schlüssel zu verwenden und die OCR dem OpenRouter-Konto zu berechnen, selbst wenn für die Inferenz ein persönlicher Anbieterschlüssel verwendet wird.[1] Andere Modellzugangsdaten sind kein Beleg dafür, dass du jetzt über ein unabhängiges Parserkontingent verfügst.

Prüfe vor einem erneuten Parsing, ob das Ergebnis bereits vorliegt

Ein hilfreicher Wiederherstellungsfall beginnt, nachdem der Parser seine Arbeit abgeschlossen hat. Angenommen, der hypothetische Bericht wurde geparst, aber jeder versuchte Inferenzanbieter konnte keine Vervollständigung erzeugen. Für Chat Completions dokumentiert OpenRouter, dass die Fehlerantwort unter error.metadata.file_annotations weiterhin Anmerkungen zur geparsten Datei enthalten kann.[1]

Das bedeutet, dass die fehlgeschlagene Antwort bereits erledigte, nützliche Arbeit enthalten kann. Lies sowohl die normalen Anmerkungen der Assistant-Nachricht als auch den dokumentierten Fehlerpfad, bevor du sie verwirfst:

Stelle in der AntwortWorauf du achten solltest
Assistant-Nachricht in Chat CompletionsWiederverwendbare file-Anmerkungen mit geparstem Inhalt und einem Datei-Hash
Chat Completions error.metadata.file_annotationsDieselbe Form geparster Dateianmerkungen, nachdem das Parsing erfolgreich war, die Inferenzanbieter jedoch fehlgeschlagen sind
Responses-Ausgabeanmerkungenfile_citation-Verweise, die nicht zurückgegeben werden können, um das Parsing zu überspringen

Diese Unterschiede stammen aus dem PDF-Leitfaden von OpenRouter.[1] Ein Verweis auf ein Dokument ist nicht dasselbe Objekt wie ein wiederverwendbares geparstes Dokument.

Bewahre die vollständige wiederverwendbare Anmerkung zusammen mit dem Dokument auf, das sie beschreibt, und folge dann für eine spätere zulässige Anfrage dem Wiederverwendungsformat für Chat Completions aus dem Leitfaden. Der geparste Inhalt und der Hash in der Anmerkung ermöglichen es, das erneute Parsing zu überspringen. Wenn du nur den Dateinamen oder den Verweis in der Antwort kopierst, übermittelst du diesen Inhalt nicht.

Wenn du Anmerkungen sowohl aus erfolgreichen als auch aus Fehlerantworten sammelst, ist laut Dokumentation file.hash die Identität für die Deduplizierung. Bewahre in deiner Anwendung die Zuordnung zum ursprünglichen Dokument auf. Im Berichtsbeispiel kann eine versehentlich angehängte Anmerkung aus einem anderen Quartalsbericht zu einer scheinbar schlüssigen Antwort auf Grundlage falscher Belege führen.

Dieser Weg gilt für geparste Verarbeitungswege. Bei der nativen Verarbeitung wird die PDF direkt weitergeleitet; dabei entstehen diese Parseranmerkungen nicht. Auch kann die Wiederverwendung einer Anmerkung keinen Versuch retten, bei dem das Parsing nie abgeschlossen wurde.[1] Gibt es kein verwendbares Parsergebnis, lass das Dokument ausstehend und behebe die fehlgeschlagene Phase, statt eine Anmerkung zu erfinden.

Gespeicherte Anmerkungen können extrahierten Text und Bilder enthalten. Behandle sie als Kopien von Dokumentinhalten, für die geeignete Zugriffs- und Aufbewahrungskontrollen gelten, und nicht als harmlose Diagnosemetadaten. Der Leitfaden zur Dateiaufbewahrung behandelt die Nachverfolgung dieser Kopien. Füge keine vollständige vertrauliche Anmerkung in ein allgemeines Fehlerprotokoll ein.

Bewahre die Dokumentversion zusammen mit dem gespeicherten Parsergebnis auf. Wenn jemand den Bericht ersetzt, aber den Dateinamen beibehält, belegt der gestern extrahierte Inhalt nicht, was die heutige Datei enthält. Prüfe vor der Wiederverwendung, ob der gespeicherte Inhalt zu der Version gehört, um die es geht; ein vertrauter Dateiname allein ist kein ausreichender Abgleich.

Stelle das Dokument zurück, ohne den gesamten Batch neu zu starten

Wenn die Antwort eine Drosselung anzeigt, prüfe die Hinweise für Wiederholungen. OpenRouter zufolge kann relevanten Antworten zu Ratenlimits oder Verfügbarkeit ein Retry-After beigefügt sein.[2] Der HTTP-Header kann eine Verzögerung in Sekunden oder ein HTTP-Datum enthalten; ein Zahlenwert ist nicht in Millisekunden angegeben.[3]

Warte eine gültige zurückgegebene Verzögerung ab, bevor du einen weiteren zulässigen Versuch unternimmst. Liegt sie jenseits der Frist des Dokumentauftrags, stelle den Auftrag sichtbar zurück, statt eine verborgene Wiederholungsschleife laufen zu lassen. Gibt es keinen brauchbaren Hinweis, folge der dokumentierten Vorgehensweise des Anbieters und begrenze sowohl die Anzahl der Versuche als auch die gesamte verstrichene Zeit.

Prüfe, ob das SDK oder der Workflow bereits Wiederholungen ausführt. Eine äußere Schleife um eine Funktion mit eigenen Wiederholungen kann mehr Versuche erzeugen, als der äußere Zähler anzeigt. Führe für die Versuche des Dokuments einschließlich der Wartezeiten einen einzigen Datensatz, damit der Batch nicht wiederholt zu einem Schritt zurückkehrt, der weiterhin eingeschränkt ist.

Bewahre bei einem Batch den Fortschritt für jedes Dokument einzeln auf. Wenn neun Berichte bereits abgeschlossen sind und der zehnte zurückgestellt wird, gehen durch einen Neustart aller zehn die nützlichen Unterschiede verloren. Führe abgeschlossene Berichte, geparste, aber unbeantwortete Berichte und Dokumente, die noch auf das Parsing warten, in getrennten Zuständen. Das ist eine Empfehlung zur Anwendungsplanung und keine Behauptung, OpenRouter verwalte deinen Batch auf diese Weise.

Stimme die Worker ab, die du kontrollierst. Mehrere Worker, die jeweils nur wenige Anfragen senden, können zusammen trotzdem eine große Spitzenlast auf derselben Route erzeugen. Eine gemeinsame Warteschlange macht die Gesamtlast sichtbar. Zusätzliche Schlüssel oder Konten sind laut Dokumentation kein Weg, mehr von der global verwalteten Kapazität von OpenRouter zu schaffen.[4]

Prüfe, was der Ersatzweg erhalten hat

Bevor du die Antwort des Berichts akzeptierst, prüfe die Informationen, die der ausgewählte Verarbeitungsweg geliefert hat. Eine zusammenhängende Textzusammenfassung und ein Vergleich aller Diagramme stellen unterschiedliche Anforderungen. Ersteres kann gelingen, obwohl Letzterem wichtige Bilder fehlen.

Für Mistral OCR dokumentiert OpenRouter, dass pro PDF höchstens acht Bilder angefordert und pro nachgelagerter Anfrage höchstens acht Bilder weitergeleitet werden. Überschüssige Bilder werden verworfen, während der extrahierte Text erhalten bleibt. Wenn das nachgelagerte Modell keine Bilder akzeptieren kann, wird nur der geparste Text weitergeleitet.[1]

Daher ist eine Antwort zu einem ausgelassenen Bild nicht allein deshalb vertrauenswürdig, weil die Anfrage erfolgreich war. Prüfe, ob die relevanten visuellen Belege vorhanden waren. Wenn du Text selbst extrahierst und an die Inferenz sendest, prüfe Tabellenstruktur, Seitenzuordnung und mögliche Informationsverluste aus Scans oder Diagrammen. Das ist dein eigener Extraktionsworkflow und keine weitere benannte OpenRouter-Engine.

Trenne die Wartezeit von bereits berechneter Arbeit

Bei einer langsamen PDF-Anfrage kann die verstrichene Zeit den Dateiabruf, das Parsing, die Modellverarbeitung und die Wartezeiten zwischen Wiederholungen umfassen. Verwende die Zeitabschnitte, die in deinem Trace tatsächlich sichtbar sind. Du kannst nicht davon ausgehen, dass ein Wechsel des Inferenzmodells die Wartezeit auf den Parser oder in deiner eigenen Warteschlange beseitigt.

Es gibt keine einzelne nützliche Zahl für die „OpenRouter-Latenz“ all dieser Wege. Halte bei jeder gemessenen Dauer die Merkmale des Dokuments, die Engine, das Modell und die Parallelität fest. Dieser Leitfaden hat keinen Latenzbenchmark durchgeführt und gibt keine erwartete Bearbeitungszeit an. Ein Zeitstempel dafür, wann der Client aufgehört hat zu warten, ist keine Messung der einzelnen entfernten Phasen.

Auch die Abrechnung richtet sich nach der geleisteten Arbeit. Native Eingaben werden nach dem Eingabepreis des Modells berechnet. Für OCR fallen gesonderte Gebühren an. Die Cloudflare-Konvertierung ist laut Dokumentation eine kostenlose Verarbeitung; dadurch wird die anschließende Modellinferenz nicht kostenlos.[1]

Der Schutz von OpenRouter bei null Vervollständigungen unterscheidet qualifizierende Modell-Tokenkosten von bereits ausgeführten Zusatzarbeiten. Je nach tatsächlich ausgeführter Arbeit und Fehlerfall können Parsing oder OCR berechnet werden, auch wenn eine spätere Antwort fehlschlägt.[5] Prüfe die Kostenaufschlüsselung, bevor du den gesamten Versuch als kostenlos bezeichnest oder ihn in deiner eigenen Schätzung doppelt berechnest.

Kehre zum letzten abgeschlossenen Schritt des Berichts zurück. Wurde die Datei nie abgerufen, korrigiere die Eingabe. Wurde das Parsing zurückgestellt, behalte den Platz in der Warteschlange bei. Gibt es wiederverwendbaren geparsten Inhalt, bewahre ihn für den nächsten geeigneten Inferenzversuch auf. Diese Wiederherstellungsentscheidung richtet sich nach dem Dokument, das du tatsächlich hast, und nicht nach einem weiteren Modellnamen in der Hoffnung, einen unveränderten Parser zu umgehen.

Wenn Sie reAPI für Dokumenteingaben prüfen

Bei reAPI folgt die Dokumenteingabe dem jeweils dokumentierten nativen Format des Modells. Medien, auch PDF-Dateien, müssen als öffentliche HTTP(S)-URLs gesendet werden; base64 und data:-URIs werden nicht akzeptiert.[6] Die Unterstützung hängt vom Modell ab: Die Referenz zu Claude Sonnet 5.5 hält zum Beispiel fest, dass PDF-Eingaben noch nicht verifiziert sind. Prüfen Sie die Modellseite, bevor Sie einen PDF-Workflow umziehen, und behalten Sie die oben beschriebene Behandlung von Rate-Limits bei, egal welcher Dienst die Datei verarbeitet.

Quellen

  1. OpenRouter, „PDF Inputs“, offizielle Dokumentation. Vollständig gelesen am 16. November 2026; Abschnitte zu Engines, API-Format, OCR-Bildern und Anmerkungen.
  2. OpenRouter, „Errors and Debugging“, offizielle Dokumentation, Abschnitte zu Fehlerumschlag, Fehlercodes und Retry-After. Abgerufen am 15. November 2026; relevante Abschnitte am 16. November geprüft.
  3. MDN, Retry-After header. Gelesen am 16. November 2026.
  4. OpenRouter, „Limits“, offizielle Dokumentation, Abschnitte zu Einführung und Umgang mit Ratenlimits. Gelesen am 16. November 2026.
  5. OpenRouter, „Zero Completion Insurance“, offizielle Dokumentation. Abgerufen am 15. November 2026; Richtlinie am 16. November vollständig geprüft, um die Unterschiede zwischen Modell-Token- und Zusatzkosten zu erfassen.
  6. reAPI. Claude-Sonnet-5.5-API-Referenz: Eingabeformate. Geprüft am 17. November 2026. Claude Sonnet 5.5.
Alle Anleitungen