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

· reAPI Team

Erreurs PDF OpenRouter : quand l’analyseur atteint sa limite de débit

Diagnostique les erreurs PDF OpenRouter en distinguant récupération du fichier, limites de l’analyseur et échecs du modèle. Compare les routes, les nouvelles tentatives et les annotations réutilisables.

Erreurs PDF OpenRouter : quand l’analyseur atteint sa limite de débit

Tu changes de modèle, renvoies le même PDF et reçois une nouvelle erreur de limite de débit du moteur d’analyse. Le modèle a changé, mais le document passe peut-être toujours d’abord par le même analyseur.

OpenRouter peut envoyer un PDF directement à un modèle prenant en charge les fichiers de façon native, ou l’analyser avant de transférer son contenu à un modèle qui ne dispose pas de cette prise en charge. La configuration par défaut documentée privilégie le traitement natif lorsqu’il est disponible et utilise sinon Mistral OCR.[1] Deux noms de modèles différents peuvent donc laisser inchangée l’étape d’analyse préalable. Identifie cette route avant de tenter à nouveau la même opération pour la même erreur.

Trouve où ce PDF s’est arrêté

Enregistre la réponse complète avec son statut, son ID de requête, le modèle sélectionné, le point de terminaison et le moteur. Consigne si le moteur était configuré par défaut ou explicitement ; ne décris pas une route non spécifiée comme si tu l’avais choisie délibérément.

Le format d’entrée dépend de l’API. Responses utilise un élément de contenu input_file avec file_url ou file_data. Chat Completions utilise une partie de contenu file.[1] Copier une requête d’un point de terminaison à un autre sans adapter ce format peut entraîner un échec avant même que la capacité de l’analyseur ne soit en cause.

Vérifie ensuite la mise à disposition du fichier. Pouvoir ouvrir un PDF dans ton navigateur connecté ne prouve pas que le service peut récupérer la même URL sans cette connexion. La documentation d’OpenRouter indique d’utiliser des URL publiques pour la récupération directe et une entrée base64 pour les documents locaux ou privés.[1] Utilise la méthode adaptée et autorisée ; rendre public un document confidentiel n’est pas nécessaire pour résoudre le problème.

Si l’erreur nomme le moteur d’analyse, conserve cette formulation. Si elle indique plutôt que le fichier n’a pas pu être récupéré, corrige d’abord sa mise à disposition. Si l’analyse est terminée mais que l’inférence a échoué, conserve le contenu analysé avant de répéter toute l’opération. L’application peut afficher un message générique « Échec du PDF » dans tous ces cas, mais les tâches à accomplir ensuite sont différentes.

Lis aussi le corps ou le flux, pas seulement le statut HTTP. OpenRouter documente des erreurs qui arrivent après l’envoi des en-têtes, y compris des échecs au sein d’une réponse qui avait commencé avec un statut de réussite.[2] Un journal HTTP qui consigne uniquement 200 peut manquer l’échec que ton application doit traiter.

Changer de modèle ne sert que si tu changes aussi la route concernée

Le guide PDF répertorie trois moteurs : native, mistral-ocr et cloudflare-ai. Le traitement natif transmet le fichier à un modèle compatible. Mistral OCR extrait le contenu du document, tandis que Cloudflare AI convertit le PDF en Markdown.[1]

Pour un rapport hypothétique contenant du texte narratif, un tableau financier et un graphique, le choix doit dépendre de la question. Une conversion en texte peut suffire pour résumer le texte narratif. Une question sur les libellés du graphique exige que ces libellés soient préservés et accessibles au modèle. Une route qui renvoie une réponse n’a pas nécessairement préservé les éléments nécessaires pour répondre à cette question.

Si tu passes d’un modèle à un autre qui nécessite la même route OCR, l’erreur de l’analyseur peut persister. Si tu sélectionnes un modèle avec prise en charge native des PDF et utilises cette route, tu changes aussi le chemin de traitement du document. Vérifie les limites d’entrée et l’adéquation du modèle exact au lieu de déduire la prise en charge à partir du nom de sa famille.

Les anciens exemples peuvent utiliser pdf-text. Le guide actuel d’OpenRouter marque ce moteur comme obsolète et redirige vers cloudflare-ai.[1] Mettre à jour le libellé clarifie la route visée, mais ne prouve pas à lui seul que la qualité de conversion ou la capacité se sont améliorées.

BYOK ne supprime pas les frais de l’étape OCR. OpenRouter indique utiliser sa propre clé Mistral pour ce travail et facturer l’OCR au compte OpenRouter, même si l’inférence utilise une clé personnelle de fournisseur.[1] Des identifiants différents pour le modèle ne prouvent pas que tu disposes désormais d’une capacité d’analyseur indépendante.

Avant d’analyser à nouveau, cherche le résultat que tu as déjà

Un cas de récupération utile commence une fois l’analyse de l’analyseur terminée. Supposons que le rapport hypothétique ait été analysé, mais que tous les fournisseurs d’inférence essayés n’aient pas réussi à produire une complétion. Pour Chat Completions, OpenRouter indique que l’erreur peut encore contenir les annotations du fichier analysé sous error.metadata.file_annotations.[1]

Cela signifie que la réponse en échec peut contenir un travail utile déjà terminé. Avant de la supprimer, lis à la fois les annotations normales du message assistant et l’emplacement documenté dans l’erreur :

Emplacement dans la réponseÉlément à rechercher
Message assistant Chat CompletionsAnnotations file réutilisables contenant le contenu analysé et un hachage de fichier
Chat Completions error.metadata.file_annotationsLa même forme d’annotation du fichier analysé après la réussite de l’analyse et l’échec des fournisseurs d’inférence
Annotations de sortie ResponsesRéférences file_citation, qui ne peuvent pas être renvoyées pour ignorer l’analyse

Ces distinctions proviennent du guide PDF d’OpenRouter.[1] Une citation pointant vers un document n’est pas le même objet qu’un document analysé réutilisable.

Conserve l’annotation réutilisable complète avec le document qu’elle décrit, puis suis le format de réutilisation Chat Completions du guide pour une prochaine requête autorisée. Le contenu analysé et le hachage de l’annotation permettent d’éviter une nouvelle analyse. Copier uniquement le nom de fichier ou la citation de la réponse ne fournit pas ce contenu.

Si tu recueilles des annotations provenant de réponses réussies et en échec, l’identifiant documenté pour la déduplication est file.hash. Dans ton application, conserve le lien avec le document d’origine. Dans l’exemple du rapport, joindre par erreur les annotations d’un autre rapport trimestriel peut produire une réponse apparemment cohérente, mais fondée sur les mauvais éléments.

Cette méthode s’applique aux routes analysées. Le traitement natif transmet directement le PDF et ne produit pas ces annotations de l’analyseur. La réutilisation d’annotations ne peut pas non plus sauver une tentative dont l’analyse n’a jamais abouti.[1] S’il n’existe aucun résultat analysé utilisable, laisse le document en attente et traite l’étape en échec au lieu de fabriquer une annotation.

Les annotations stockées peuvent contenir du texte et des images extraits. Traite-les comme des copies du contenu du document nécessitant des contrôles d’accès et de conservation adaptés, et non comme de simples métadonnées de diagnostic. Le guide de conservation des fichiers explique comment suivre ces copies. Évite de placer une annotation confidentielle complète dans un journal d’erreurs généraliste.

Conserve la version du document avec le résultat d’analyse enregistré. Si quelqu’un remplace le rapport tout en gardant son nom de fichier, le contenu extrait hier ne permet pas d’établir ce que contient le fichier d’aujourd’hui. Avant réutilisation, vérifie que le contenu enregistré correspond à la version concernée ; un nom de fichier familier ne suffit pas à établir cette correspondance.

Diffère le document sans redémarrer tout le lot

Lorsque la réponse indique une limitation de débit, examine ses indications de nouvelle tentative. OpenRouter précise qu’un Retry-After peut accompagner les réponses concernées de limite de débit ou de disponibilité.[2] La valeur de l’en-tête HTTP peut être un délai en secondes ou une date HTTP ; une valeur numérique n’est pas exprimée en millisecondes.[3]

Attends le délai valide renvoyé avant une nouvelle tentative autorisée. S’il dépasse l’échéance du traitement du document, diffère visiblement ce traitement au lieu de laisser tourner une boucle de nouvelle tentative invisible. En l’absence d’indication exploitable, suis la procédure documentée du fournisseur et limite à la fois le nombre de tentatives et la durée totale écoulée.

Vérifie si le SDK ou le workflow effectue déjà des tentatives. Une boucle externe autour d’une fonction qui réessaie peut entraîner davantage de tentatives que le nombre affiché par le compteur externe. Garde un seul historique des tentatives du document, y compris des attentes, afin que le lot ne revienne pas sans cesse à une étape toujours limitée.

Pour un lot, conserve l’avancement de chaque document. Si neuf rapports sont déjà terminés et que le dixième est différé, redémarrer les dix fait perdre une distinction utile. Maintiens des états distincts pour les rapports terminés, ceux qui sont analysés mais sans réponse et les documents qui attendent encore l’analyse. Il s’agit d’une recommandation de planification applicative, pas d’une affirmation selon laquelle OpenRouter gère ainsi ton lot.

Coordonne les workers que tu contrôles. Plusieurs workers envoyant chacun un petit nombre de requêtes peuvent tout de même créer ensemble un pic important sur la même route. Une file partagée rend visible la charge globale. La documentation ne présente pas l’ajout de clés ou de comptes comme un moyen d’augmenter la capacité globale régie par OpenRouter.[4]

Vérifie ce que la route de remplacement a conservé

Avant d’accepter la réponse du rapport, examine les informations fournies par la route sélectionnée. Un résumé continu du texte et une comparaison de chaque graphique ont des exigences différentes. Le premier peut réussir même si le second manque d’images essentielles.

Pour Mistral OCR, OpenRouter documente une demande d’au plus huit images par PDF et le transfert d’au plus huit images par requête en aval. Les images excédentaires sont supprimées tandis que le texte extrait est conservé. Si le modèle en aval ne peut pas accepter les images, seul le texte analysé est transféré.[1]

Par conséquent, tu ne peux pas faire confiance à une réponse portant sur une image omise au seul motif que la requête a réussi. Vérifie si les éléments visuels pertinents étaient présents. Si tu choisis d’extraire toi-même le texte et de l’envoyer à l’inférence, examine la structure des tableaux, la correspondance des pages et toute information perdue dans les scans ou les diagrammes. C’est ton propre workflow d’extraction, pas un autre moteur OpenRouter nommé.

Distingue l’attente du travail déjà facturé

Pour une requête PDF lente, le temps écoulé peut inclure la récupération du fichier, l’analyse, le traitement par le modèle et les attentes entre les nouvelles tentatives. Utilise les intervalles réellement visibles dans ta trace. Tu ne peux pas supposer qu’un changement de modèle d’inférence supprime le temps passé à attendre l’analyseur ou à patienter dans ta propre file.

Il n’existe pas de chiffre unique utile de « latence OpenRouter » pour toutes ces routes. Pour chaque durée mesurée, conserve les caractéristiques du document, le moteur, le modèle et la concurrence. Ce guide n’a réalisé aucun benchmark de latence et ne donne pas de délai d’exécution attendu. L’horodatage indiquant quand le client a cessé d’attendre ne mesure pas chacune des étapes distantes.

La facturation suit aussi le travail effectué. Les entrées natives sont facturées selon le tarif d’entrée du modèle. L’OCR entraîne des frais distincts. La conversion Cloudflare est documentée comme un traitement gratuit, ce qui ne rend pas gratuite l’inférence du modèle qui suit.[1]

La protection d’OpenRouter en cas de complétion nulle distingue les frais de jetons de modèle admissibles des travaux auxiliaires déjà effectués. L’analyse ou l’OCR peuvent quand même être facturés lorsqu’une réponse ultérieure échoue, selon le travail réel et le cas d’échec.[5] Consulte le détail des frais avant de qualifier toute la tentative de gratuite ou de la facturer deux fois dans ton propre calcul.

Reviens à la dernière étape terminée du rapport. Si le fichier n’a jamais été récupéré, corrige l’entrée. Si l’analyse est différée, conserve sa place dans la file. Si un contenu analysé réutilisable existe, garde-le pour la prochaine tentative d’inférence appropriée. Cette décision de récupération suit le document dont tu disposes réellement plutôt qu’un autre nom de modèle choisi dans l’espoir de contourner un analyseur inchangé.

Si vous évaluez reAPI pour l’entrée de documents

Sur reAPI, l’entrée de documents suit le format natif documenté de chaque modèle. Les médias, y compris les fichiers PDF, doivent être envoyés sous forme d’URL HTTP(S) publiques ; base64 et les URI data: ne sont pas acceptés.[6] La prise en charge dépend du modèle : la référence de Claude Sonnet 5.5 indique par exemple que l’entrée PDF n’a pas encore été vérifiée. Consultez la page du modèle avant de migrer un flux PDF, et conservez la gestion des limites de débit décrite plus haut, quel que soit le service qui traite le fichier.

Références

  1. OpenRouter, « PDF Inputs », documentation officielle. Lu intégralement le 16 novembre 2026 ; sections sur les moteurs, le format API, les images OCR et les annotations.
  2. OpenRouter, « Errors and Debugging », documentation officielle, sections sur l’enveloppe d’erreur, les codes d’erreur et Retry-After. Récupéré le 15 novembre 2026 ; sections pertinentes examinées le 16 novembre.
  3. MDN, Retry-After header. Lu le 16 novembre 2026.
  4. OpenRouter, « Limits », documentation officielle, sections sur l’introduction et la gestion des limites de débit. Lu le 16 novembre 2026.
  5. OpenRouter, « Zero Completion Insurance », documentation officielle. Récupéré le 15 novembre 2026 ; politique intégrale examinée le 16 novembre pour distinguer les coûts des jetons de modèle et les frais auxiliaires.
  6. reAPI. Référence de l’API Claude Sonnet 5.5 : formats d’entrée. Vérifié le 17 novembre 2026. Claude Sonnet 5.5.
Tous les guides