Idempotency
Ensuring Single Execution with Idempotency Keys
Idempotency keys help ensure that certain API operations are processed only once, even if the request is retried due to network interruptions or other transient issues. This mechanism is particularly useful for operations that create resources or trigger actions where duplicate execution would result in unintended effects.
Header: IDEMPOTENCY-KEY
IDEMPOTENCY-KEY
To use idempotency, include the IDEMPOTENCY-KEY
header in your API requests. The value should be a random universally unique identifier (UUID). For example:
IDEMPOTENCY-KEY: 123e4567-e89b-12d3-a456-426614174000
How It Works
- Single Processing: When a request with an
IDEMPOTENCY-KEY
is received, the API processes it and stores the result associated with the key. - Subsequent Requests: If the same
IDEMPOTENCY-KEY
is used in a subsequent request, the API returns the originally stored result instead of processing the operation again. - Preventing Duplicates: This ensures that the action is performed only once, even if the client retries the request.
Usage Example: Creating an Auto Ramp
When creating an auto ramp, include an IDEMPOTENCY-KEY to ensure the operation is processed only once. For example:
Request
POST /autoramp
Content-Type: application/json
IDEMPOTENCY-KEY: 123e4567-e89b-12d3-a456-426614174000
{
"name": "Auto Ramp 1",
"parameters": {
"threshold": 100,
"duration": "30d"
}
}
Response (First Request)
201 Created
{
"id": "ar_1A2B3C4D",
"name": "Auto Ramp 1",
"parameters": {
"threshold": 100,
"duration": "30d"
},
"status": "active"
}
Response (Retry with Same Key)
201 Created
{
"id": "ar_1A2B3C4D",
"name": "Auto Ramp 1",
"parameters": {
"threshold": 100,
"duration": "30d"
},
"status": "active"
}
Key Considerations
- Uniqueness: Use a unique IDEMPOTENCY-KEY for each operation. Reusing a key for different operations may result in unintended behavior.
- Errors: If the initial request fails due to a validation or processing error, retries with the same IDEMPOTENCY-KEY will return the same error response.
When to Use Idempotency Keys
The API requests requiring idempotency keys mention it in the API documentation.
Updated 1 day ago