---
schema_version: "1"
id: db103d07b83056353b4e3872d4d2fd59f0629b80f63227c56e670ee1f969105f
title: Prevent Record Duplication with Idempotent Record Writes
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/uiapi/ui_api_features_records_idempotent.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_idempotent.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: 94df739398e6efaab6d778af6ed920318475f0fcbc727502a5104fecb99294df
description: Use idempotent record writes to avoid duplication of records and server operations, which can occur when an app or client encounters a network connection issue.
---
# Prevent Record Duplication with Idempotent Record Writes

Use idempotent record writes to avoid duplication of records and server operations, which can occur when an app or client encounters a network connection issue.

To make a request idempotent, include an Idempotency-Key value in your request header. By making a request idempotent, your records on the server remain in the same state even if an identical request is made once or multiple times. Salesforce uses server storage to store the cached response of an idempotent request.

Only the /ui-api/records/{recordId} resource supports idempotent record writes for the POST, PATCH, and DELETE methods. The following table describes idempotent record write support for specific UI API resources.

<table class="featureTable sort_table" summary="">




        <thead class="thead sorted" align="left">
          <tr>
            <th class="featureTableHeader  " id="d3235e54">UI API Resource</th>

            <th class="featureTableHeader  " id="d3235e57">POST</th>

            <th class="featureTableHeader  " id="d3235e60">PATCH</th>

            <th class="featureTableHeader  " id="d3235e63">DELETE</th>

          </tr>

        </thead>

        <tbody class="tbody">
          <tr>
            <td class="entry" headers="d3235e54" data-title="UI API Resource"><a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_records_create.htm" title="Create or clone a record."><samp class="codeph nolang">/ui-api/records</samp></a></td>

            <td class="entry" headers="d3235e57" data-title="POST"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

            <td class="entry" headers="d3235e60" data-title="PATCH"></td>

            <td class="entry" headers="d3235e63" data-title="DELETE"></td>

          </tr>

          <tr>
            <td class="entry" headers="d3235e54" data-title="UI API Resource"><a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_patch.htm" title="Update a record's data."><samp class="codeph nolang">/ui-api/records/{recordId}</samp></a></td>

            <td class="entry" headers="d3235e57" data-title="POST"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

            <td class="entry" headers="d3235e60" data-title="PATCH"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

            <td class="entry" headers="d3235e63" data-title="DELETE"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

          </tr>

          <tr>
            <td class="entry" headers="d3235e54" data-title="UI API Resource"><a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_content_document.htm" title="Upload documents and images or update the file with a new version."><samp class="codeph nolang">/ui-api/records/content-documents/​content-versions</samp></a></td>

            <td class="entry" headers="d3235e57" data-title="POST"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

            <td class="entry" headers="d3235e60" data-title="PATCH"></td>

            <td class="entry" headers="d3235e63" data-title="DELETE"></td>

          </tr>

          <tr>
            <td class="entry" headers="d3235e54" data-title="UI API Resource"><a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_content_document.htm" title="Upload documents and images or update the file with a new version."><samp class="codeph nolang">/ui-api/records/content-documents/​${contentDocumentId}/content-versions</samp></a></td>

            <td class="entry" headers="d3235e57" data-title="POST"><img class="image" src="https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/checkmark_16x16.png" alt="Yes"></td>

            <td class="entry" headers="d3235e60" data-title="PATCH"></td>

            <td class="entry" headers="d3235e63" data-title="DELETE"></td>

          </tr>

        </tbody>

      </table>

When a unique Idempotency-Key request header is passed to a supported resource, the response for a server data mutation operation is stored. Subsequently, next time a request is sent to the same resource with the same Idempotency-Key value, the cached response is returned instead of performing a server data mutation operation.

![Note](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/icon_note.png)

#### Note

An idempotent request supports a response size up to 9 MB. If your request results in a larger response size, idempotency isn’t honored, but the request doesn’t fail. Retrying the same request results in duplication on the server.

Idempotent record writes save server processing costs by returning cached response for POST, PATCH, and DELETE operations.

## Include an Idempotency Key Value

In your request header, pass in an [Idempotency-Key value](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header) in the [UUID v4 format](https://datatracker.ietf.org/doc/html/rfc4122). You can use a library that supports UUID v4 generation, including the [Java UUID utility](https://docs.oracle.com/javase/7/docs/api/java/util/UUID.html).

curl --location --request POST 'https://MyDomainName.my.salesforce.com/services/data/v56.0/ui-api/records' \\
--header 'Authorization: Bearer AuthToken' \\
--header 'Content-Type: application/json' \\
--header '**Idempotency-Key: 12cfe4e6-e477-4de8-aa4e-95d31aa2be24**' \\
--header 'Cookie: BrowserId=yVVAfz9GEeuRCtc5jOsncA; CookieConsentPolicy=0:0' \\
--data-raw '{
    "apiName": "ResourceAbsence",
    "fields": {
        "CreatedDate": "2022-12-01T14:52:16.000Z",
        "LastModifiedDate": "2022-12-01T14:52:16.000Z",
        "ResourceId": "0Hnxx0000004C92CAE",
        "Start": "2022-12-02T14:52:16.000Z",
        "End": "2022-12-03T14:52:16.000Z"
    }
}'

![Tip](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/images/icon_note_tip.png)

#### Tip

We recommend that you use a unique Idempotency-Key header value for each unique operation. The idempotency key doesn't provide idempotency indefinitely and auto-expires after 30 days if the same key is reused.

When the idempotency key expires after 30 days, the cached record that’s associated with the idempotency key is deleted. If the same idempotency key is used again after it’s deleted, the key is treated as a new idempotency key. A new cached response is then stored when an idempotent request is received the first time.

## Example: Upload a File With An Idempotency Key

Let’s look at how you can [upload a file](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_content_document.htm "Upload documents and images or update the file with a new version.") using an idempotency key. To send the idempotent request, include Idempotency-Key in your request header.

curl -H "X-PrettyPrint: 1" \\
-F 'json={"title":"Example image", "description":"Your description"}' \\
-F "fileData=@image.jpg;type=application/octet-stream" \\
-X POST https://MyDomainName.my.salesforce.com/services/data/v58.0/ui-api/records/content-documents/content-versions \\
-H 'Authorization: Bearer AuthToken' \\
-H 'Idempotency-Key: YourKey'

When you send the request, notice the id values in the contentDocument, contentDocumentLinks, and contentVersion fields. If you resend the request using the same idempotency key, the response is returned without any server-side operations and the id values remain the same, indicating that the file doesn’t get uploaded a second time.

## HTTP Status Error Codes

An idempotent request returns [2XX status codes](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_errors.htm "The response header contains an HTTP status code. If the response isn’t successful, the response body contains an error message, and if appropriate, information about the field or object where the error occurred.") for a successful operation. It can also return one of these HTTP status error codes.

400

You can receive one of the following errors.

- Idempotency not supported—Remove the Idempotency-Key header and retry the operation.
- Idempotency-Key is not in valid format—Generate a new Idempotency-Key header value and retry the operation.

409

Either a different user has issued the same request earlier or this duplicate request is issued within a short time because an earlier request terminated abruptly. If you include a Retry-After header, a follow-up request is sent.

422

The Idempotency-Key header value is already used by the same user for a different request. Generate a new Idempotency-Key value and retry the operation.

5XX

A server error has occurred. If you include a Retry-After header, a follow-up request is sent.