Обработка ошибок в рабочем процессе NextPDF Connect

Кратко

Создавайте отказоустойчивые рабочие процессы Connect. Проверяйте каждый результат инструмента, закрывайте сбойную сессию и повторяйте попытку из чистого состояния. Инструмент при сбое возвращает структурированный результат с ошибкой. Воспринимайте этот результат как обычный ответ, а не как сбой транспорта. PHP Standards Recommendation (PSR)-18 проводит то же различие: ответ возвращается, даже если статус указывает на ошибку (PSR-18 §3).

Установка

composer require nextpdf/server

Привяжите транспорт. В этом рецепте используются create_pdf, add_text и output_pdf. Все три инструмента относятся к Core.

Концептуальный обзор

Сбойный вызов инструмента возвращает результат с ошибкой. Результат содержит флаг ошибки, понятное человеку сообщение и код, когда он применим. Успешный результат не содержит флага ошибки и несёт обычный вывод инструмента. В обоих случаях транспорт отправил запрос и получил ответ (PSR-18 §p2).

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

Поверхность API

Инструмент	Роль	Уровень риска
`create_pdf`	Открывает сессию	Safe (безопасный)
`add_text`	Записывает текст	Caution (осторожность)
`output_pdf`	Отрисовывает и возвращает PDF	Approval Required / Review (требуется подтверждение / проверка, base64)

Единый источник истины — каталог инструментов. Доступные инструменты зависят от установленного уровня.

Пример кода — быстрый старт

Выполните успешный сценарий (create_pdf → add_text → output_pdf) и проверьте каждый результат. Затем намеренно повторно используйте уже уничтоженный document_id в add_text, чтобы вызвать ошибку сессии. Восстановитесь, создав новую сессию и воспроизведя содержимое.

Пример кода — продакшен

Классифицируйте ошибки по категориям и реагируйте соответственно:

Проверка входных данных — детерминированная ошибка. Исправьте аргументы, затем повторите тот же вызов. Примеры: пустой текст, недопустимое выравнивание, неположительный размер, неизвестный размер страницы, неизвестное семейство шрифтов.
Сессия — document_id больше не существует. Создайте новую сессию и воспроизведите всё содержимое.
Система — ограничение ресурсов сервера, например лимит сессий. Сделайте паузу и повторите попытку.
Одобрение — вызов output_pdf с записью в файл может приостановиться для одобрения человеком. Это пауза рабочего процесса, а не сбой. Передайте запрос на подтверждение и дождитесь решения, затем повторите вызов с токеном подтверждения.

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

Граничные случаи и подводные камни

Одобрение не является ошибкой. Запрос на подтверждение человеком (HITL) — это пауза. Не повторяйте попытки в цикле без паузы. Передайте его человеку.
Перезапуск сервера. Все сессии в памяти очищаются, и каждый прежний document_id становится недействительным.
Частичный рабочий процесс. Если add_text завершается сбоем в середине документа, сессия может оказаться в несогласованном состоянии. Безопасное восстановление — это новая сессия, а не частичное исправление.

Производительность

Накладные расходы незначительны. Этот рецепт охватывает поток управления, а не отрисовку. Профиль любого создаваемого вывода — structural.

Замечания по безопасности

Сообщения об ошибках предназначены для вызывающего агента и оператора. Не передавайте необработанный текст серверной ошибки дословно недоверенным конечным пользователям. Вместо этого выводите классифицированное, очищенное сообщение.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор источника)
Транспорт возвращает ответ независимо от результата.	PSR-18	§p2
Ответ возвращается даже при статусе с ошибкой.	PSR-18	§3

Коммерческий контекст

Неприменимо — все инструменты относятся к Core.

Доступность транспортов

Транспорт	Доступен	Примечания
MCP (через stdio)	Да	Ошибки поступают как результат инструмента с флагом ошибки.
REST	Да	Статус, отличный от 2xx, содержит то же классифицированное тело ошибки.
gRPC	Да	Код статуса и сообщение результата с ошибкой.

В любом транспорте рассматривайте ошибку на уровне инструмента как обычный ответ, а не как сбой транспорта (PSR-18 §3).

Уровень риска HITL

create_pdf относится к Safe, add_text — к Caution, а output_pdf — к Approval Required, понижаемому до Review в режиме base64. Ожидающая одобрения запись в файл появляется в виде запроса на одобрение. Цикл обработки ошибок должен рассматривать это как паузу, а не как сбой (уровни риска HITL).

JSON-конверт шлюза подтверждения

При ожидании одобрения возвращается:

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

Повторно вызовите тот же инструмент, указав этот токен в _confirmation_token. В ответ возвращается { "allowed": true }. Полный процесс описан в разделе output-approval.