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.

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/{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.

UI API Resource	POST	PATCH	DELETE
`/ui-api/records`
`/ui-api/records/{recordId}`
`/ui-api/records/content-documents/content-versions`
`/ui-api/records/content-documents/${contentDocumentId}/content-versions`

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

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.

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