Надёжность
Ошибки API и повторные запросы
По статусу и коду ответа определите, нужно ли исправить запрос, подождать, сменить тариф или повторить операцию.
Формат ответа
У ошибок нет единой схемы. Ошибки аутентификации и часть ошибок проверки содержат поле message. Для ошибок с отдельным сценарием обработки API также возвращает стабильное поле code и дополнительные данные, если они нужны.
/take может вернуть изображение, а 202 и ошибки — JSON. Не сохраняйте тело в файл изображения до проверки HTTP-статуса и Content-Type.Исправьте запрос
400 означает некорректный URL, JSON, параметр или Idempotency-Key. Сюда же относятся неподдерживаемые browser/format, недоступный или запрещённый адрес и параметры строки запроса для POST /take. При неверном типе содержимого API возвращает 415.
Проверка запроса использует стабильные коды INVALID_WAIT_UNTIL, INVALID_DELAY, DELAY_TOO_LARGE, WAIT_SELECTOR_TOO_LONG, INVALID_WAIT_SELECTOR, INVALID_CAPTURE_SELECTOR, CAPTURE_SELECTOR_TOO_LONG и SELECTOR_FULL_PAGE_CONFLICT. Исправьте значение перед повтором.
Не повторяйте такой запрос без изменений. Исправьте данные или передайте Content-Type: application/json.
Исправьте аутентификацию
401 с сообщением Missing API key означает, что заголовка X-API-Key нет. Invalid API key означает, что ключ неверен, отключён или отозван. Исправьте или замените ключ вместо повторов с теми же учётными данными.
Смените тариф или дождитесь новой квоты
402 PAID_PLAN_REQUIRED означает, что операция доступна только на PAID. На FREE создавайте задачи через асинхронный API.
402 SCREENSHOT_QUOTA_EXCEEDED означает, что месячная квота исчерпана. Немедленный повтор её не восстановит. Возможности тарифов описаны в разделе «Тарифы и ограничения API».
Разрешите конфликт Idempotency-Key
409 IDEMPOTENCY_KEY_REUSED означает, что ключ уже использован с другими параметрами. Повторите исходный запрос с этим ключом либо создайте новый ключ для действительно новой операции. Правила выбора ключа описаны в руководстве по безопасным повторам.
Проверьте цель после ошибки задачи
422 SCREENSHOT_TASK_FAILED означает, что воркер не смог создать скриншот. Ответ не раскрывает внутреннее исключение. Сначала проверьте доступность целевой страницы и параметры; новый запрос не обязательно завершится успешно.
После создания задачи Chromium может безопасно завершить её с INVALID_WAIT_SELECTOR или INVALID_CAPTURE_SELECTOR, если синтаксис CSS некорректен. CAPTURE_SELECTOR_NOT_FOUND означает, что элемент для снимка не появился, CAPTURE_SELECTOR_NOT_VISIBLE — что подходящий элемент не получил положительных видимых границ, а CAPTURE_REGION_TOO_LARGE — что физическая площадь изображения элемента превышает 16 777 216 пикселей. NAVIGATION_TIMEOUT означает тайм-аут навигации, WAIT_SELECTOR_TIMEOUT — тайм-аут ожидания готовности, а RENDER_TIMEOUT сохраняется для совместимой классификации тайм-аута снимка или отмены выполнения.
При повторе POST /take с тем же Idempotency-Key вернётся ошибка существующей задачи. Новый ключ или запрос без ключа создаёт новую задачу и расходует квоту.
Подождите и повторите
| Ответ | Действие клиента |
|---|---|
429 | Сделайте паузу и повторите запрос; ограничьте число попыток. |
429 SYNC_WAIT_CAPACITY_EXCEEDED | Достигнут предел одновременных ожиданий /take. Выдержите Retry-After: 2. |
503 | Сервис временно недоступен. Увеличивайте паузу между повторами и ограничьте число попыток. |
503 SCREENSHOT_OBJECT_UNAVAILABLE | Для идемпотентного POST /take подождите и повторите запрос с тем же Idempotency-Key. |
Для обычного 429 и ответов 503 заголовок Retry-After не гарантируется. При повторе той же операции POST /take сохраняйте прежний Idempotency-Key. Не отправляйте запросы в непрерывном цикле.
Новый ключ или запрос без ключа может создать ещё одну задачу. Для GET /take идемпотентность не поддерживается: повтор может создать другую оплачиваемую задачу.
Проверьте статус после 202
202 от /take — не ошибка. Тело содержит JSON и statusUrl, задача продолжает выполняться, а проверка статуса не расходует квоту повторно. Этот ответ содержит Retry-After: 2. Обработка ответа показана в руководстве по синхронному API.
Сетевой сбой до ответа
Клиент не может знать, успел ли сервер создать задачу. Повторяйте тот же POST /take с прежним Idempotency-Key.
POST /v1/screenshots пока не поддерживает Idempotency-Key. Повтор после неизвестного результата может создать ещё одну задачу и снова израсходовать квоту.