GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Все руководства

· reAPI Team

Ошибки PDF в OpenRouter: что делать, если парсер упёрся в лимит запросов

Диагностируй ошибки PDF в OpenRouter, разделяя получение файла, ограничения парсера и сбои модели. Сравни маршруты обработки, повторы и повторно используемые аннотации файлов.

Ошибки PDF в OpenRouter: что делать, если парсер упёрся в лимит запросов

Ты меняешь модель, снова отправляешь тот же PDF и получаешь очередную ошибку о лимите запросов движка анализа. Модель изменилась, но документ всё ещё может сначала проходить через тот же парсер.

OpenRouter может отправить PDF напрямую модели с нативной поддержкой файлов или сначала обработать его, а затем передать содержимое модели без такой поддержки. Согласно документации, по умолчанию при наличии возможности используется нативная обработка, а в противном случае — Mistral OCR.[1] Поэтому два разных названия моделей могут оставить предыдущий этап обработки неизменным. Прежде чем снова пытаться обойти ту же ошибку, выясни, по какому маршруту идёт документ.

Выясни, на каком этапе остановился этот PDF

Сохрани полный ответ со статусом, ID запроса, выбранной моделью, эндпоинтом и движком. Зафиксируй, была ли настройка движка стандартной или заданной явно; не описывай неуказанный маршрут так, будто ты выбрал его намеренно.

Формат входных данных зависит от API. Responses использует элемент содержимого input_file с file_url или file_data. Chat Completions использует часть содержимого file.[1] Если скопировать запрос между эндпоинтами и не адаптировать формат, он может завершиться ошибкой ещё до того, как станет важна пропускная способность парсера.

Затем проверь доставку файла. То, что PDF открывается в браузере с активной сессией, не означает, что сервис сможет получить тот же URL без этой авторизации. В документации OpenRouter указаны публичные URL для прямого получения и ввод в формате base64 для локальных или приватных документов.[1] Используй подходящий разрешённый способ; публиковать конфиденциальный документ для диагностики не требуется.

Если ошибка называет движок анализа, сохрани эту формулировку. Если в ней сказано, что файл не удалось получить, сначала исправь доставку. Если анализ завершился, но вывод модели не удался, сохрани обработанное содержимое до повторения всей операции. Во всех этих случаях приложение может показать общее сообщение «Ошибка обработки PDF», но дальнейшие действия будут разными.

Читай не только HTTP-статус, но и тело ответа или поток. В документации OpenRouter описаны ошибки, которые поступают уже после отправки заголовков, в том числе сбои внутри ответа, начавшегося с успешного статуса.[2] HTTP-логгер, записывающий только 200, может пропустить ошибку, которую должно обработать твоё приложение.

Смена модели помогает, только если меняется нужный маршрут

В руководстве по PDF перечислены три движка: native, mistral-ocr и cloudflare-ai. Нативная обработка передаёт файл поддерживаемой модели. Mistral OCR извлекает содержимое документа, а Cloudflare AI преобразует PDF в Markdown.[1]

Для гипотетического отчёта с текстовым описанием, финансовой таблицей и графиком выбор должен зависеть от вопроса. Для краткого изложения текста может быть достаточно преобразования в текст. Если вопрос касается подписей на графике, эти подписи нужно сохранить и передать модели. Маршрут, который вернул ответ, не обязательно сохранил доказательства, необходимые для ответа на этот вопрос.

Если переключиться между двумя моделями, которым нужен один и тот же маршрут OCR, ошибка парсера может сохраниться. Если выбрать модель с нативной поддержкой PDF и использовать этот маршрут, изменится и путь обработки документа. Проверяй ограничения ввода и пригодность именно этой модели, а не делай вывод о поддержке по названию семейства.

В старых примерах может использоваться pdf-text. В текущем руководстве OpenRouter этот движок помечен как устаревший и перенаправляется на cloudflare-ai.[1] Обновление метки прояснит предполагаемый маршрут, но само по себе не доказывает улучшение качества преобразования или пропускной способности.

BYOK не отменяет плату за этап OCR. OpenRouter сообщает, что использует для этой работы собственный ключ Mistral и списывает стоимость OCR с аккаунта OpenRouter, даже если для вывода модели используется личный ключ провайдера.[1] Другие учётные данные модели не доказывают, что теперь у тебя есть отдельная квота парсера.

Перед повторным анализом проверь, нет ли уже готового результата

Полезный сценарий восстановления начинается после завершения работы парсера. Предположим, гипотетический отчёт уже обработан, но ни один из испробованных провайдеров вывода модели не смог сформировать завершённый ответ. Для Chat Completions OpenRouter документирует, что ошибка всё ещё может содержать аннотации обработанного файла в error.metadata.file_annotations.[1]

Это значит, что неудачный ответ может содержать полезную уже выполненную работу. Прежде чем отбрасывать его, прочитай и обычные аннотации сообщения assistant, и документированное расположение аннотаций в ошибке:

Расположение в ответеЧто искать
Сообщение assistant в Chat CompletionsПовторно используемые аннотации 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 или рабочий процесс. Внешний цикл вокруг помощника, который сам повторяет запросы, может создать больше попыток, чем показывает внешний счётчик. Веди одну запись всех попыток для документа, включая ожидания, чтобы пакет не возвращался снова и снова к этапу, который всё ещё ограничен.

В пакетной обработке сохраняй прогресс отдельно для каждого документа. Если девять отчётов уже завершены, а десятый отложен, перезапуск всех десяти уничтожит полезное различие. Разделяй завершённые отчёты, обработанные, но оставшиеся без ответа отчёты и документы, всё ещё ожидающие анализа. Это рекомендация по планированию приложения, а не утверждение, что OpenRouter управляет твоим пакетом таким образом.

Координируй рабочие процессы, которыми ты управляешь. Несколько процессов, отправляющих каждый понемногу запросов, могут вместе создать большой всплеск на одном маршруте. Общая очередь делает совокупную нагрузку видимой. В документации нет указания, что дополнительные ключи или аккаунты позволяют увеличить глобально регулируемую пропускную способность OpenRouter.[4]

Проверь, что сохранил новый маршрут

Прежде чем принять ответ по отчёту, проверь информацию, которую предоставил выбранный маршрут. Для связного текстового резюме и сравнения всех графиков нужны разные данные. Первое может получиться, даже если для второго не хватает важных изображений.

Для Mistral OCR OpenRouter документирует запрос не более 8 изображений на PDF и передачу не более 8 изображений в одном последующем запросе. Лишние изображения удаляются, а извлечённый текст сохраняется. Если последующая модель не может принимать изображения, передаётся только обработанный текст.[1]

Поэтому нельзя доверять ответу об отсутствующем изображении только потому, что запрос завершился успешно. Проверь, были ли в запросе нужные визуальные данные. Если ты решишь сам извлечь текст и отправить его на вывод модели, проверь структуру таблиц, соответствие страниц и любые потери информации из сканов или диаграмм. Это твой собственный процесс извлечения, а не ещё один именованный движок OpenRouter.

Отделяй ожидание от уже оплаченной работы

При медленном запросе PDF прошедшее время может включать получение файла, анализ, обработку моделью и ожидания между повторами. Используй интервалы, которые действительно видны в трассировке. Нельзя предполагать, что смена модели для вывода устранит время ожидания парсера или нахождения в собственной очереди.

Для всех этих маршрутов нет единого полезного показателя «задержки OpenRouter». Вместе с измеренной длительностью записывай особенности документа, движок, модель и степень параллелизма. Это руководство не проводило тест производительности по задержкам и не указывает ожидаемое время завершения. Время, когда клиент прекратил ожидание, — не то же самое, что измерение каждого удалённого этапа.

Оплата также зависит от выполненной работы. Нативный ввод тарифицируется по цене входных данных модели. За OCR взимается отдельная плата. Преобразование Cloudflare документировано как бесплатная обработка, но последующий вывод модели от этого не становится бесплатным.[1]

Защита OpenRouter при нулевом количестве завершённых ответов отделяет подходящие под условия расходы на токены модели от стоимости уже выполненной вспомогательной работы. В зависимости от фактически выполненной работы и конкретного сбоя за анализ или OCR всё ещё могут взиматься деньги, даже если последующий ответ не удался.[5] Прежде чем считать всю попытку бесплатной или дважды учитывать её стоимость в собственной оценке, проверь разбивку расходов.

Вернись к последнему завершённому этапу отчёта. Если файл так и не был получен, исправь входные данные. Если анализ отложен, сохрани его место в очереди. Если есть пригодное для повторного использования обработанное содержимое, сохрани его для следующей подходящей попытки вывода модели. Такой выбор способа восстановления зависит от реального состояния документа, а не от другого названия модели в надежде обойти неизменившийся парсер.

Если вы рассматриваете reAPI для работы с документами

В reAPI документы передаются в нативном формате, описанном в документации каждой модели. Медиафайлы, включая PDF, нужно отправлять как публичные HTTP(S)-URL; base64 и URI data: не принимаются.[6] Поддержка зависит от модели: например, в справочнике по Claude Sonnet 5.5 указано, что ввод PDF ещё не проверен. Перед переносом процесса с PDF проверьте страницу модели и сохраните описанную выше обработку ограничений частоты, какой бы сервис ни обрабатывал файл.

Источники

  1. OpenRouter, «PDF Inputs», официальная документация. Полностью прочитана 16 ноября 2026 года; разделы о движках, формате API, изображениях OCR и аннотациях.
  2. OpenRouter, «Errors and Debugging», официальная документация, разделы об оболочке ошибки, кодах ошибок и Retry-After. Получена 15 ноября 2026 года; соответствующие разделы изучены 16 ноября.
  3. MDN, Retry-After header. Прочитана 16 ноября 2026 года.
  4. OpenRouter, «Limits», официальная документация, разделы «Введение» и «Обработка ограничений частоты запросов». Прочитана 16 ноября 2026 года.
  5. OpenRouter, «Zero Completion Insurance», официальная документация. Получена 15 ноября 2026 года; политика полностью изучена 16 ноября, чтобы проверить различия между расходами на токены модели и дополнительными расходами.
  6. reAPI. Справочник по API Claude Sonnet 5.5: форматы ввода. Проверено 17 ноября 2026 года. Claude Sonnet 5.5.
Все руководства