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

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

1. Single Processing: When a request with an IDEMPOTENCY-KEY is received, the API processes it and stores the result associated with the key.
2. 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.
3. 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.