Документация·Идемпотентность
🔁

Идемпотентность

Как заголовок `Idempotency-Key` защищает от двойного списания при ретраях на нестабильных сетях.

Зачем это

Сети падают в середине запроса. Если вы делаете POST /v1/activations и соединение обрывается до получения ответа, вы не знаете, была ли активация создана. Наивный retry может списать дважды.

Заголовок Idempotency-Key решает это: пришлите тот же ключ на retry — получите тот же результат.

Как использовать

Сгенерируйте UUID на логическую операцию, отсылайте его на каждом retry:

KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -d '{"country":"ua", "service":"telegram"}'

Повтор того же запроса с тем же Idempotency-Key возвращает оригинальный ответ — без второй активации, без второго списания.

TTL

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

Где применяется

Все POST /v1/* ендпоинты которые создают или списывают: активации, аренда, депозиты, продления. Read-ендпоинты (GET) уже идемпотентны и игнорируют заголовок.

Конфликты

Если переиспользовать ключ с другим body — API возвращает 409 idempotency_conflict. Либо держите body идентичным на ретраях, либо генерируйте новый ключ.

Поведение SDK

Официальные SDK автоматически генерируют idempotency-keys для каждого create-вызова и переиспользуют их на автоматических retry. Можно переопределить явным ключом.

← ПредыдущаяSDKСледующая →OpenAPI и Postman