Skip to main content
Network errors, timeouts, and unexpected disconnections can cause a request to fail on the client side even after the UMW API has already received and processed it. Without a mechanism to deduplicate retries, a naive retry loop risks creating duplicate releases, tracks, or deliveries — problems that can be disruptive and time-consuming to unwind. Idempotency keys solve this by allowing you to safely retry any mutating request with the guarantee that the platform will process it exactly once.

​
How Idempotency Works

1

Generate a unique key for each logical operation

Before sending a mutating request (POST or PATCH), generate a UUID v4 and store it alongside the operation context in your application. This key represents a single logical intent — for example, “create release for album Midnight Sessions.”
2

Include the key in the Idempotency-Key header

Pass the UUID as the value of the Idempotency-Key request header. The header must be present on every attempt of the same operation.
3

Retry safely on network failure

If you receive a network-level error, a timeout, or a 500/503 response, retry the request using the same Idempotency-Key. The UMW platform will recognize the key and return the original response rather than processing the request a second time.
4

Receive the deduplicated response

On a replayed request, the API returns the original HTTP status code and response body, along with an Idempotent-Replayed: true header indicating that the response was served from cache rather than live processing.

​
Key Expiry

Idempotency keys are stored by the UMW platform for 24 hours from the time of the first request. After expiry, a request with the same key value will be processed as a new operation. For long-running workflows that span multiple days, generate a fresh key for each new execution rather than reusing a key from a previous run.

​
Example Request

The following curl command creates a new release with an idempotency key. If the command is interrupted and re-run with the same key, UMW will return the original response without creating a second release.
A successful first request returns 201 Created. All subsequent requests with the same key return 201 Created with the original response body and the Idempotent-Replayed: true header — no duplicate release is created.

​
Supported Endpoints

Idempotency keys are supported on all mutating endpoints listed below. Using the Idempotency-Key header on endpoints not in this list has no effect and the header will be silently ignored.

​
Idempotency Key Mismatch

If you send a request using an Idempotency-Key that was previously used with a different request body, the UMW API will reject the request with a 422 Unprocessable Entity error and the idempotency_key_mismatch error code:
This error protects you from accidentally mutating a resource with mismatched data. Common causes include:
  • Reusing a key constant across multiple different operations in your codebase
  • Copying a key from a previous run and modifying the request payload
  • Using a static key during development that persists between test iterations
To resolve this error, generate a fresh UUID for the new operation and discard the previously used key.
Generate a fresh UUID v4 per logical operation — not per HTTP request. For example, create one key for the entire release creation flow, one key for each track you’re uploading, and one key each time you submit a delivery. Tying a key to a logical operation (rather than a raw request) makes it natural to reuse the same key across retries of that operation while avoiding cross-operation collisions.