> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iron.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Use the IDEMPOTENCY-KEY header to ensure write operations are processed only once. Prevents duplicate resource creation from retried requests.

## 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:

```bash theme={null}
IDEMPOTENCY-KEY: 123e4567-e89b-12d3-a456-426614174000
```

### How It Works

<Steps>
  <Step title="Single Processing">
    When a request with an `IDEMPOTENCY-KEY` is received, the API processes it and stores the result associated with the key.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Preventing Duplicates">
    This ensures that the action is performed only once, even if the client retries the request.
  </Step>
</Steps>

### Usage Example: Creating an Autoramp

When creating an Autoramp, include an `IDEMPOTENCY-KEY` to ensure the operation is processed only once. For example:

#### Request

<CodeGroup>
  ```bash theme={null}
  curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "IDEMPOTENCY-KEY: 123e4567-e89b-12d3-a456-426614174000" \
    -H "X-API-Key: <your-api-key>" \
    -d '{
      "source_currencies": [{
        "type": "Fiat",
        "code": "EUR"
      }],
      "destination_currency": {
        "type": "Crypto",
        "token": "USDC",
        "blockchain": "Ethereum"
      },
      "recipient_account": {
        "type": "Crypto",
        "blockchain": "Ethereum",
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      },
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_is_third_party": false
    }'
  ```
</CodeGroup>

#### Response (First Request)

<CodeGroup>
  ```json theme={null}
  {
    "id": "f8f9a8c7-d8b1-4f1a-8f15-7e6c8a1a8e50",
    "status": "Authorized",
    "kind": "Onramp",
    "created_at": "2025-01-20T12:34:56Z"
  }
  ```
</CodeGroup>

#### Response (Retry with Same Key)

<CodeGroup>
  ```json theme={null}
  {
    "id": "f8f9a8c7-d8b1-4f1a-8f15-7e6c8a1a8e50",
    "status": "Authorized",
    "kind": "Onramp",
    "created_at": "2025-01-20T12:34:56Z"
  }
  ```
</CodeGroup>

### 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

API endpoints that require idempotency keys are marked in the API documentation.