Идемпотентность и безопасные повторы

Сетевой тайм-аут не показывает, завершилось ли изменение до потери ответа. Для перечисленных ниже операций передавайте 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 с jitter. Идемпотентность предотвращает повторное выполнение, но не делает неограниченные повторы или высокую параллельность безопасными.

Поддерживаемые операции

Публичный контракт принимает 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 и признаки завершения сброса описаны на странице Сброс и готовность порта.