Ідемпотентність і безпечні повтори

Мережевий таймаут не показує, чи завершилася зміна до втрати відповіді. Для наведених нижче операцій передавайте Idempotency-Key, щоб безпечно повторити той самий логічний запит.

Ключ запиту та ID вебхука — різні речі

Idempotency-Key захищає вихідний запит на зміну даних в API. Поле id події вебхука захищає ваш обробник від повторної обробки вхідної події.

Передавання ключа

Створюйте новий UUID для кожної нової логічної зміни й передавайте його в заголовку:

curl -X POST "https://api.ltesocks.io/v2/ports/10000/reset" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: 7c838e2d-7d52-42e7-aed1-528829cbd514"

Офіційні SDK створюють ключ автоматично для підтримуваних мутацій. Передайте збережений UUID явно, якщо продовжуєте той самий логічний запит після перезапуску застосунку:

JavaScript

const port = await client.ports.reset({
  id: '10000',
  idempotencyKey: '7c838e2d-7d52-42e7-aed1-528829cbd514',
});

Python

from uuid import UUID

port = client.ports.reset(
    "10000",
    idempotency_key=UUID("7c838e2d-7d52-42e7-aed1-528829cbd514"),
)

PHP

<?php

$port = $client->ports()->reset(
    '10000',
    '7c838e2d-7d52-42e7-aed1-528829cbd514',
);

Зберігайте ключ разом із методом, шляхом і тілом, доки результат не стане відомим. Повторно використовуйте його лише для точного повтору цього запиту. Для нової дії, іншого шляху або зміненого тіла створюйте новий UUID.

Коли API повертає раніше збережений результат, відповідь містить:

Idempotency-Replayed: true

Повтор зберігає початкову відповідь та її заголовки, зокрема Retry-At і Retry-After, якщо вони були присутні.

Рішення щодо повтору

Результат	Дія
З’єднання закрилося або минув таймаут до отримання відповіді	Повторити точний запит із тим самим ключем
Ресурс уже містить потрібну зміну	Не надсилати запит на зміну повторно
Помилка валідації або автентифікації	Усунути причину; для зміненого запиту використати новий ключ
Відповідь про cooldown скидання	Зачекати до Retry-After або Retry-At, а потім перевірити, чи потрібен той самий логічний запит
Навмисний запуск наступної зміни	Створити новий ключ

Для тимчасових помилок використовуйте обмежений експоненційний backoff із випадковим відхиленням. Ідемпотентність запобігає повторному виконанню, але не робить безпечними необмежені повтори чи високу паралельність.

Підтримувані операції

Публічний контракт приймає Idempotency-Key для таких змін:

Область	Операції
Обліковий запис	POST /user/preferences
Замовлення	POST /ports/order
Тариф	POST /ports/{id}/extend, POST /ports/{id}/plan
Налаштування порту	POST /ports/{id}/tags, POST /ports/{id}/autorenew, POST /ports/{id}/signature, POST /ports/{id}/credentials, POST /ports/{id}/autoreset
Підключення	POST /ports/{id}/reset

Не додавайте заголовок до кожного POST автоматично. Наприклад, фільтрування POST /ports і сумісні операції видалення не документують підтримку ідемпотентності. Перевіряйте наявність заголовка для конкретної операції в довіднику API.

Cooldown і ознаки завершення скидання описані на сторінці Скидання та готовність порту.