Ошибки и повторы CloudPrint API
Обрабатывайте HTTP-статусы, машиночитаемые ошибки, ограничения частоты запросов, трассировку и безопасные повторы.
Стабильная структура ошибки
Ошибки содержат error, необязательный error_code, безопасное пояснение message и структурированные сведения details. Ветвите логику по машиночитаемым полям и HTTP-статусу, а не по тексту сообщения.
Трассировка запросов
Каждый ответ содержит X-Request-Id. Сохраняйте его рядом с бизнес-идентификатором, print_job_id и временем запроса.
Когда повторять запрос
Повторяйте 429 после срока из Retry-After, а временные ошибки 5xx — с ограниченной экспоненциальной задержкой. После 401 один раз обновите токен. После 403 исправьте разрешения, после 400 или 422 — данные запроса, после 415 — формат. Не повторяйте создание задания без исходного Idempotency-Key.
Ошибки во время печати
Принятый API-запрос всё ещё может завершиться заданием со статусом failed. Прочитайте failure_reason и сравните формат и параметры с возможностями принтера.