К содержанию
ShotlyДокументация API

Надёжность

Безопасные повторы с Idempotency-Key

Если соединение оборвалось до ответа, повторите POST /take с тем же Idempotency-Key. API использует исходную задачу и не спишет квоту повторно.

Где поддерживается

Idempotency-Key необязателен и поддерживается только для POST /take. Добавляйте его, если клиент может повторить запрос после сетевого сбоя.

Idempotency-Key не поддерживается для GET /take и асинхронного POST /v1/screenshots.

Добавьте ключ

shell
IDEMPOTENCY_KEY="shotly-$(date +%s)-$$"

curl --silent --show-error \
  --request POST "https://api.shotly.cloud/take" \
  --header "X-API-Key: $SHOTLY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "url": "https://example.com",
    "browser": "chromium",
    "format": "png",
    "fullPage": true
  }'

Полный разбор бинарного и JSON-ответа приведён в руководстве по синхронному API.

Требования к ключу

Длина ключа — от 8 до 128 символов. Разрешённые символы: [A-Za-z0-9._:-].

Передавайте ключ только в заголовке Idempotency-Key. Ключи сравниваются отдельно для каждого API-ключа; одинаковое значение у разных API-ключей не связывает задачи.

Повтор того же запроса

Shotly использует исходную задачу: квота повторно не резервируется и новая задача не создаётся. API снова ждёт выполняющуюся задачу; если ограничение синхронных ожиданий достигнуто, он возвращает 202, а обработка продолжается.

Idempotency-Key гарантирует повторное использование одной задачи на уровне API. Если соединение оборвалось до ответа, повторите запрос с тем же ключом.

Завершённая задача возвращает прежний результат, а задача со статусом ERROR — ту же ошибку.

В ответах 200, 202 и 422 для операции с ключом API возвращает Idempotency-Key и X-Idempotency-Replayed. Заголовок X-Shotly-Task-Id возвращается с изображением при 200 и JSON-ответом при 202.

X-Idempotency-Replayed: true означает, что API использовал существующую задачу; false — что задача была создана этим запросом.

Ключ с другими параметрами

Если тот же ключ уже связан с другим запросом, API возвращает 409 Conflict с кодом IDEMPOTENCY_KEY_REUSED. Новая задача не создаётся, квота не расходуется.

Повторите исходный запрос с этим ключом либо создайте новый ключ для новой операции.

Как сравниваются запросы

Сравниваются нормализованные url, browser, format, fullPage, selector, размер экрана, масштаб и параметры готовности waitUntil, delayMs, waitForSelector. Отсутствующее поле waitUntil означает автоматический совместимый режим; остальные пропущенные параметры равны своим значениям по умолчанию. jpg равен jpeg, а порядок полей JSON не влияет на сравнение.

Срок хранения

Текущий срок хранения ключа — 24 часа. После истечения этого срока запрос с тем же ключом может создать новую оплачиваемую задачу. Не используйте ключ как постоянный бизнес-идентификатор.

Порядок повтора

text
Запрос отправлен
├─ Получен 200, 202 или ответ с ошибкой → обработайте ответ
└─ Соединение прервалось до ответа
   └─ повторите тот же POST с тем же Idempotency-Key

Рекомендации по обработке кодов ответа собраны на странице «Ошибки API и повторные запросы». API-ключ храните по правилам раздела «Аутентификация».