· reAPI Team
Errores de PDF en OpenRouter: cuando el analizador alcanza el límite de solicitudes
Diagnostica errores de PDF en OpenRouter distinguiendo la recuperación del archivo, los límites del analizador y los fallos del modelo. Compara rutas, reintentos y anotaciones reutilizables.

Cambias de modelo, vuelves a enviar el mismo PDF y recibes otro error de límite de solicitudes del motor de análisis. El modelo ha cambiado, pero puede que el documento siga pasando primero por el mismo analizador.
OpenRouter puede enviar un PDF directamente a un modelo que admita archivos de forma nativa o analizarlo antes de reenviar el contenido a un modelo que no tenga esa compatibilidad. La configuración predeterminada documentada da prioridad al procesamiento nativo cuando está disponible y, en caso contrario, usa Mistral OCR.[1] Por lo tanto, dos nombres de modelo distintos pueden dejar sin cambios el paso de análisis anterior. Identifica esa ruta antes de gastar otro intento en el mismo error.
Averigua dónde se detuvo este PDF
Guarda la respuesta completa con su estado, ID de solicitud, modelo seleccionado, endpoint y motor. Registra si la configuración del motor era la predeterminada o explícita; no describas una ruta sin especificar como si la hubieras elegido deliberadamente.
El formato de entrada depende de la API. Responses usa un elemento de contenido input_file con file_url o file_data. Chat Completions usa una parte de contenido file.[1] Copiar una solicitud entre endpoints sin adaptar ese formato puede provocar un fallo antes de que la capacidad del analizador importe.
Después, comprueba la entrega del archivo. Poder abrir un PDF en tu navegador con sesión iniciada no demuestra que el servicio pueda recuperar la misma URL sin esa sesión. La documentación de OpenRouter indica que se usen URL públicas para la recuperación directa y entrada base64 para documentos locales o privados.[1] Usa el método adecuado y permitido; hacer público un documento confidencial no es necesario para solucionar el problema.
Si el error menciona el motor de análisis, conserva esa formulación. Si en cambio dice que no se pudo recuperar el archivo, corrige primero la entrega. Si el análisis terminó pero falló la inferencia, conserva el contenido analizado antes de repetir toda la operación. Todos estos casos pueden producir el mensaje genérico «Error en el PDF» de una aplicación, pero requieren tareas posteriores distintas.
Lee el cuerpo o el flujo, además del estado HTTP. OpenRouter documenta errores que llegan después de que se hayan enviado los encabezados, incluidos fallos dentro de una respuesta que comenzó con un estado correcto.[2] Un registrador HTTP que solo registra 200 puede pasar por alto el fallo que tu aplicación debe gestionar.
Cambiar de modelo solo ayuda si también cambia la ruta pertinente
La guía de PDF enumera tres motores: native, mistral-ocr y cloudflare-ai. El procesamiento nativo reenvía el archivo a un modelo compatible. Mistral OCR extrae el contenido del documento, mientras que Cloudflare AI convierte el PDF a Markdown.[1]
Ante un informe hipotético con texto narrativo, una tabla financiera y un gráfico, la elección debe depender de la pregunta. Una conversión de texto puede bastar para resumir la narración. Una pregunta sobre las etiquetas del gráfico requiere que esas etiquetas se conserven y estén disponibles para el modelo. Una ruta que devuelve una respuesta no necesariamente ha conservado las pruebas necesarias para esa pregunta.
Si cambias entre dos modelos que necesitan la misma ruta OCR, el error del analizador puede continuar. Si eliges un modelo con compatibilidad nativa con PDF y usas esa ruta, también habrás cambiado el flujo de procesamiento del documento. Comprueba los límites de entrada y la idoneidad del modelo exacto, en lugar de deducir la compatibilidad por el nombre de una familia.
Los ejemplos antiguos pueden usar pdf-text. La guía actual de OpenRouter marca ese motor como obsoleto y lo redirige a cloudflare-ai.[1] Actualizar la etiqueta aclara la ruta prevista, pero eso por sí solo no demuestra que hayan mejorado la calidad de conversión o la capacidad.
BYOK no elimina la tarifa de la fase OCR. OpenRouter indica que usa su propia clave de Mistral para ese trabajo y cobra el OCR a la cuenta de OpenRouter aunque la inferencia use una clave personal del proveedor.[1] Usar credenciales distintas para el modelo no demuestra que ahora tengas una cuota de analizador independiente.
Antes de analizar de nuevo, busca el resultado que ya tienes
Un caso de recuperación útil comienza cuando el analizador ya ha terminado. Supón que se analizó el informe hipotético, pero ninguno de los proveedores de inferencia intentados logró generar una respuesta completa. Para Chat Completions, OpenRouter documenta que el error todavía puede contener las anotaciones del archivo analizado en error.metadata.file_annotations.[1]
Eso significa que la respuesta fallida puede incluir trabajo útil que ya se completó. Antes de descartarla, lee tanto las anotaciones normales del mensaje assistant como la ubicación documentada en el error:
| Ubicación en la respuesta | Qué buscar |
|---|---|
| Mensaje assistant de Chat Completions | Anotaciones file reutilizables con contenido analizado y un hash de archivo |
Chat Completions error.metadata.file_annotations | La misma estructura de anotaciones del archivo analizado después de que el análisis haya tenido éxito, pero los proveedores de inferencia hayan fallado |
| Anotaciones de salida de Responses | Referencias file_citation, que no pueden devolverse para omitir el análisis |
Estas distinciones proceden de la guía de PDF de OpenRouter.[1] Una cita que apunta a un documento no es el mismo objeto que un documento analizado reutilizable.
Guarda la anotación reutilizable completa junto con el documento que describe y luego sigue el formato de reutilización de Chat Completions de la guía para una solicitud posterior permitida. El contenido analizado y el hash de la anotación son los que permiten omitir un nuevo análisis. Copiar solo el nombre del archivo o la cita de la respuesta no aporta ese contenido.
Si recopilas anotaciones tanto de respuestas correctas como de errores, la identidad documentada para deduplicarlas es file.hash. Conserva en tu aplicación la asociación con el documento original. En el ejemplo del informe, adjuntar por accidente anotaciones de otro informe trimestral podría producir una respuesta aparentemente coherente basada en pruebas equivocadas.
Esta ruta se aplica a las rutas analizadas. El procesamiento nativo reenvía el PDF directamente y no produce estas anotaciones del analizador. La reutilización de anotaciones tampoco puede rescatar un intento cuyo análisis nunca terminó.[1] Si no hay un resultado analizado utilizable, deja el documento pendiente y resuelve la etapa fallida en vez de inventar una anotación.
Las anotaciones almacenadas pueden contener texto e imágenes extraídos. Trátalas como copias del contenido del documento que requieren controles adecuados de acceso y retención, no como metadatos de diagnóstico inocuos. La guía de retención de archivos aborda cómo hacer seguimiento de esas copias. Evita incluir una anotación confidencial completa en un registro de errores de uso general.
Conserva la versión del documento junto con el resultado de análisis guardado. Si alguien sustituye el informe pero mantiene su nombre de archivo, el contenido extraído ayer no demuestra qué contiene el archivo de hoy. Antes de reutilizarlo, verifica que el contenido guardado corresponda a la versión sobre la que se pregunta; un nombre de archivo conocido no basta para confirmar que coincide.
Aplaza el documento sin reiniciar todo el lote
Cuando la respuesta indique limitación de solicitudes, revisa las instrucciones para reintentar. OpenRouter dice que las respuestas pertinentes de límite de solicitudes o disponibilidad pueden incluir un Retry-After.[2] El encabezado HTTP puede indicar una demora en segundos o una fecha HTTP; un valor numérico no está expresado en milisegundos.[3]
Espera el intervalo válido devuelto antes de otro intento permitido. Si supera el plazo del trabajo del documento, aplázalo de forma visible en vez de mantener en ejecución un bucle de reintentos oculto. Si no hay una indicación útil, sigue el procedimiento documentado del proveedor y limita tanto el número de intentos como el tiempo total transcurrido.
Comprueba si el SDK o el flujo de trabajo ya reintenta. Un bucle externo alrededor de una función que ya reintenta puede generar más intentos que los que muestra el contador externo. Mantén un único registro de los intentos del documento, incluidas las esperas, para que el lote no vuelva repetidamente a un paso que sigue sujeto a restricciones.
En un lote, conserva el progreso de cada documento. Si nueve informes ya se completaron y el décimo se aplaza, reiniciar los diez elimina una distinción útil. Mantén estados separados para los informes completados, los analizados pero sin respuesta y los documentos que aún esperan análisis. Esta es una recomendación de planificación de la aplicación, no una afirmación de que OpenRouter gestione tu lote de ese modo.
Coordina los workers que controlas. Varios workers que envían cada uno unas pocas solicitudes pueden crear, en conjunto, un gran pico en la misma ruta. Una cola compartida hace visible la carga agregada. La documentación no presenta las claves o cuentas adicionales como una forma de crear más capacidad de OpenRouter, que se gestiona globalmente.[4]
Comprueba qué conservó la ruta alternativa
Antes de aceptar la respuesta del informe, revisa la información que proporcionó la ruta elegida. Un resumen continuo de texto y una comparación de todos los gráficos tienen requisitos distintos. El primero puede salir bien aunque al segundo le falten imágenes importantes.
Para Mistral OCR, OpenRouter documenta que se pueden solicitar como máximo 8 imágenes por PDF y reenviar no más de 8 por solicitud posterior. Las imágenes sobrantes se descartan mientras se conserva el texto extraído. Si el modelo posterior no puede aceptar imágenes, solo se reenvía el texto analizado.[1]
Por lo tanto, no puedes confiar en una respuesta sobre una imagen omitida solo porque la solicitud haya tenido éxito. Comprueba si estaba presente la información visual pertinente. Si decides extraer tú el texto y enviarlo a inferencia, revisa la estructura de las tablas, la correspondencia de páginas y cualquier información perdida de los escaneos o diagramas. Ese es tu propio flujo de extracción, no otro motor de OpenRouter con nombre distinto.
Separa la espera del trabajo que ya se ha cobrado
En una solicitud de PDF lenta, el tiempo transcurrido puede incluir la recuperación del archivo, el análisis, el procesamiento del modelo y las esperas entre reintentos. Usa los intervalos que realmente sean visibles en tu traza. No des por hecho que cambiar el modelo de inferencia elimina el tiempo de espera del analizador o de tu propia cola.
No existe una única cifra útil de «latencia de OpenRouter» para todas estas rutas. Registra las características del documento, el motor, el modelo y la concurrencia junto con cualquier duración medida. Esta guía no ha ejecutado una prueba de latencia ni asigna un tiempo de finalización esperado. La marca de tiempo que indica cuándo el cliente dejó de esperar no equivale a medir cada etapa remota.
La facturación también depende del trabajo realizado. La entrada nativa se cobra según el precio de entrada del modelo. El OCR tiene cargos separados. La conversión de Cloudflare está documentada como procesamiento gratuito, pero eso no hace gratuita la inferencia posterior del modelo.[1]
La protección de OpenRouter para cero respuestas completas distingue los cargos que cumplen los requisitos por tokens del modelo del trabajo auxiliar ya realizado. El análisis u OCR todavía pueden cobrarse aunque falle una respuesta posterior, según el trabajo real y el tipo de fallo.[5] Consulta el desglose de cargos antes de considerar gratuito todo el intento o de cobrarlo dos veces en tu propia estimación.
Vuelve al último paso completado del informe. Si nunca se recuperó el archivo, corrige la entrada. Si se aplazó el análisis, conserva su lugar en la cola. Si existe contenido analizado reutilizable, guárdalo para el siguiente intento de inferencia adecuado. Esa decisión de recuperación se basa en el documento que realmente tienes, no en elegir otro nombre de modelo con la esperanza de evitar un analizador que no ha cambiado.
Si evalúas reAPI para la entrada de documentos
En reAPI, la entrada de documentos sigue el formato nativo documentado de cada modelo. Los medios, incluidos los archivos PDF, deben enviarse como URL HTTP(S) públicas; no se aceptan base64 ni URI data:.[6] La compatibilidad depende del modelo: por ejemplo, la referencia de Claude Sonnet 5.5 indica que la entrada PDF aún no se ha verificado. Consulta la página del modelo antes de trasladar un flujo con PDF y mantén el manejo de límites de velocidad descrito arriba, sea cual sea el servicio que procese el archivo.
Referencias
- OpenRouter, “PDF Inputs”, documentación oficial. Leída íntegramente el 16 de noviembre de 2026; secciones sobre motores, formato de API, imágenes OCR y anotaciones.
- OpenRouter, “Errors and Debugging”, documentación oficial, secciones sobre estructura del error, códigos de error y Retry-After. Consultada el 15 de noviembre de 2026; secciones pertinentes revisadas el 16 de noviembre.
- MDN, Retry-After header. Leída el 16 de noviembre de 2026.
- OpenRouter, “Limits”, documentación oficial, secciones de introducción y gestión de límites de solicitudes. Leída el 16 de noviembre de 2026.
- OpenRouter, “Zero Completion Insurance”, documentación oficial. Consultada el 15 de noviembre de 2026; política leída íntegramente el 16 de noviembre para distinguir los cargos por tokens del modelo de los cargos auxiliares.
- reAPI. Referencia de la API de Claude Sonnet 5.5: formatos de entrada. Revisado el 17 de noviembre de 2026. Claude Sonnet 5.5.