Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex Cloud API concepts
  • Basic principles
    • Overview
    • Asynchronous operations
    • Operation object
    • Idempotency

In this article:

  • Examples
  • Example 1
  • Example 2
  1. Working with operations
  2. Idempotency

Idempotency

Written by
Yandex Cloud
Updated at April 23, 2025
  • Examples
    • Example 1
    • Example 2

Yandex Cloud services support idempotency. An idempotent operation returns the same result for multiple calls.

By default, some operations in the API are not idempotent, e.g., operations that change the state of resources. To make them idempotent, specify the Idempotency-Key header in your requests. The header must contain the UUID. Generate the UUIDs for each operation separately.

Idempotency-Key: <UUID>

We recommend using a v4 UUID.

As soon as the service gets your request with the Idempotency-Key header, it will check if an operation with this UUID had been created previously. If so, the server will return the Operation object with this operation's current status. If no operation with this UUID is found, the service will start executing it.

Note

AI services, such as Yandex Foundation Models, Yandex SpeechKit, Yandex Translate, and Yandex Vision OCR, do no support idempotency even with the Idempotency-Key header.

Examples

The examples below demonstrate how to use idempotency when working with Yandex Cloud APIs.

Example 1

Let's assume you sent a start VM request:

POST /compute/v1/instances/e0m97h0gbq0foeuis03:start
HTTP/1.1
Host: compute.api.cloud.yandex.net
Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4ebf052e9aa

If you send this request again with the same Idempotency-Key, the server will not restart the VM. Instead, the server will return the Operation object containing the status of the operation called as a result of the first request.

Example 2

In this scenario, a race condition occurs.

Let's assume that a client sent a request to stop a running VM. No Idempotency-Key header was specified.

The connection failed when sending the request and the client did not receive a response from the server. The VM was stopped, but the client does not know the operation status as they have not received any response.

At the same time, another client restarts this VM, e.g., using the UI console.

However, when the first client reconnects to the internet, they will resend the stop VM request. Since there is no Idempotency-Key header, the VM the second client needs will be stopped.

If the first client had provided Idempotency-Key in their stop VM requests, the VM would not be stopped when resending the request.

Was the article helpful?

Previous
Operation object
Yandex project
© 2025 Yandex.Cloud LLC