[Документация Yandex Cloud](../../index.md) > [Концепции API Yandex Cloud](../index.md) > Работа с операциями > Идемпотентность

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

Сервисы Yandex Cloud поддерживают механизм [идемпотентности](https://ru.wikipedia.org/wiki/Идемпотентность). Идемпотентная операция — это операция, которая при многократном вызове возвращает один и тот же результат. 

По умолчанию некоторые операции в API не являются идемпотентными. Например, операции, которые изменяют состояние ресурсов. Для обеспечения их идемпотентности, в запросах необходимо передавать заголовок `Idempotency-Key`.  В заголовке следует указать UUID-строку — ее необходимо сформировать самостоятельно. У каждой операции должен быть свой UUID.

```
Idempotency-Key: <UUID>
```

Обратите внимание, рекомендуется использовать UUID **версии 4**.

Когда сервис получит запрос с заголовком `Idempotency-Key`, он проверит, была ли ранее создана операция с таким UUID. Если операция была создана, сервер вернет объект `Operation` с текущим статусом этой операции. Если операции с таким UUID не найдено, сервис начнет ее выполнение.


{% note info %}

Сервисы искусственного интеллекта Yandex AI Studio, Yandex SpeechKit, Yandex Translate и Yandex Vision OCR не поддерживают идемпотентность даже с заголовком `Idempotency-Key`.

{% endnote %}


## Примеры {#examples}

На примерах ниже показано, как использовать механизм идемпотентности при работе с API Yandex Cloud.

### Пример 1 {#example-1}
 
Например, вы отправили запрос на запуск [виртуальной машины](../../glossary/vm.md):

```
POST /compute/v1/instances/e0m97h0gbq0foeuis03:start
HTTP/1.1
Host: compute.api.cloud.yandex.net
Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4ebf052e9aa
```
 
Если снова отправить этот запрос c тем же `Idempotency-Key`, сервер не будет выполнять повторный запуск машины. Вместо этого сервер вернет объект `Operation` — он будет содержать статус операции, которая была вызвана при первом запросе.

### Пример 2 {#example-2}
 
Данный пример демонстрирует ситуацию, в которой возникает [состояние гонки](https://ru.wikipedia.org/wiki/%D0%A1%D0%BE%D1%81%D1%82%D0%BE%D1%8F%D0%BD%D0%B8%D0%B5_%D0%B3%D0%BE%D0%BD%D0%BA%D0%B8).
 
Пусть с одного клиента был отправлен запрос на остановку запущенной виртуальной машины. Заголовок `Idempotency-Key` при этом не указан.

Предположим, что при отправке запроса произошел сбой в соединении, и клиент не получил ответ от сервера. Виртуальная машина была остановлена, но так как ответ не был получен, клиент не будет знать статуса операции.

В это время другой клиент заново запускает эту виртуальную машину (например, через UI-консоль).

Но когда у первого клиента появится доступ к интернету, он повторно отправит запрос на остановку машины. Так как заголовок `Idempotency-Key` не используется, виртуальная машина, которая необходима второму клиенту, будет остановлена.

Если бы в запросах на остановку машины первый клиент передавал `Idempotency-Key`, то при повторной отправке запроса виртуальная машина не была бы остановлена.