Prevent Record Duplication with Idempotent Record Writes (Beta)

Use idempotent record writes to avoid duplication of records and server operations. To make a request idempotent, include an Idempotency-Key value in your request header.

Contact Salesforce to enable Idempotent Record Writes for UI API. This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

Note

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 resource supports idempotent record writes for the POST, PATCH, and DELETE requests.

Note

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.

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 a Idempotency-Key value in the UUID v4 format. You can use a library that supports UUID v4 generation, including the Java UUID utility..

1curl --location --request POST 'https://<Host>/services/data/v56.0/ui-api/records' \
2--header 'Authorization: Bearer <AuthToken>' \
3--header 'Content-Type: application/json' \
4--header 'Idempotency-Key: 12cfe4e6-e477-4de8-aa4e-95d31aa2be24' \
5--header 'Cookie: BrowserId=yVVAfz9GEeuRCtc5jOsncA; CookieConsentPolicy=0:0' \
6--data-raw '{
7    "apiName": "ResourceAbsence",
8    "fields": {
9        "CreatedDate": "2022-12-01T14:52:16.000Z",
10        "LastModifiedDate": "2022-12-01T14:52:16.000Z",
11        "ResourceId": "0Hnxx0000004C92CAE",
12        "Start": "2022-12-02T14:52:16.000Z",
13        "End": "2022-12-03T14:52:16.000Z"
14    }
15}'
16

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.

Note

If the idempotency key expired, the record is deleted with cached response from the server. Using an expired idempotency key is equivalent to using a new key.

HTTP Status Error Codes

An idempotent request returns 2XX status codes 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.

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.

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.

5XX

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

User Interface API Developer Guide

Prevent Record Duplication with Idempotent Record Writes (Beta)

Include an Idempotency Key Value

HTTP Status Error Codes