Idempotency ensures that an API request produces the same result regardless of how many times it is sent. This is particularly important for operations that modify state, like creating accounts or signing transactions, where duplicate requests could cause unintended side effects.
The CDP APIs support idempotency through the X-Idempotency-Key header. When you include an idempotency key with a request, the API responds as follows:
Processes the request as normal if it’s the first use of the key within the last 24 hours
Returns the exact same response as the first request if the same request is retried with the same key
Returns an error if the same key is used with different request parameters
This mechanism ensures that temporary issues like network failures don’t result in duplicate operations.
Each unique request must use a new UUID v4. The API strictly enforces the UUID v4 format requirement and will reject any other format. Here’s how to generate a valid UUID v4 in different languages:
Copy
Ask AI
import { v4 as uuidv4 } from 'uuid';// Generate a new idempotency keyconst idempotencyKey = uuidv4();
You can identify endpoints that support idempotency by looking for the X-Idempotency-Key parameter in the documentation for the related endpoint. When present, this optional header parameter indicates that the endpoint supports idempotent requests.
For example, in the Create an EVM account endpoint documentation, you’ll see a field that allows you to pass the X-Idempotency-Key header.
Generally, all POST endpoints that modify state (like creating accounts or signing transactions) support idempotency.
If you provide an idempotency key that is not a valid UUID v4, the API will reject the request:
Copy
Ask AI
{ "errorType": "invalid_request", "errorMessage": "parameter \"X-Idempotency-Key\" in header has an error: must be a valid UUID v4 format (e.g., 8e03978e-40d5-43e8-bc93-6894a57f9324)"}
This occurs when you use the same idempotency key with different request parameters:
Copy
Ask AI
{ "errorType": "idempotency_error", "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."}
This error occurs in certain highly-concurrent scenarios whereby you send multiple requests within a short period with the same idempotency key. Note that under normal circumstances, sending the same request with the same idempotency
key within a 24-hour period will return the same response as the first request.
Copy
Ask AI
{ "errorType": "already_exists", "errorMessage": "Another request with the same idempotency key is currently processing."}