Диагностика агентов, принтеров и заданий
Начинайте со статуса задания и идентификатора запроса, затем проверяйте принтер, агент и исходный документ. Такой порядок помогает быстро найти проблемный слой и не создать повторную печать.
Сначала соберите идентификаторы
Запишите номер заказа или документа в вашей системе, print_job_id, printer_id, последний статус, failure_reason и X-Request-Id. Не создавайте новое задание, пока не выяснили, было ли принято первое. При повторе исходного запроса используйте тот же Idempotency-Key.
Принтер отсутствует или offline
Убедитесь, что локальный агент работает и подключён к тому же аккаунту CloudPrint. Проверьте очередь принтера в операционной системе, затем обновите список. Маршрутизируйте по printer_id, а не по имени. Если агент offline, сначала восстановите его исходящий доступ в сеть.
API отклоняет задание
401 обычно означает недействительный или истёкший токен — запросите новый один раз. 403 указывает на отсутствующий scope. 409 означает конфликт идемпотентности или неподдерживаемый маршрут. 422 говорит о неверном payload или опциях печати, 415 — о неподдерживаемом формате.
Задание слишком долго остаётся pending
Проверьте online-статус назначенного агента и принтера. Задание не может попасть в отключённую точку. Продолжайте опрос с ограниченным интервалом и честно показывайте оператору ожидание; не создавайте копии автоматически.
Ошибка после передачи агенту
Сопоставьте failure_reason, формат документа и запрошенные параметры с возможностями принтера. Частые причины: нет PDF renderer-а, принтер не объявил нужный RAW-язык или недоступна системная печать. Для этикеток также проверьте DPI, размер носителя, драйвер, очередь и калибровку.
Обращение в поддержку
Передайте X-Request-Id, print_job_id, примерное время, аккаунт, названия агента и принтера, формат документа, параметры и видимую причину ошибки. Не отправляйте client secret, access token и конфиденциальное содержимое документа.
Чек-лист перед запуском
- Сохраняйте идентификаторы заданий и причины ошибок для поддержки и мониторинга.
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.