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

# Idempotency

> Use the X-Idempotency-Key header to safely retry requests.

## Overview

Idempotency ensures that performing the same operation multiple times produces the same result as performing it once. This protects against duplicate operations when requests are retried due to timeouts or network failures.

## How it works

### The X-Idempotency-Key header

Mutating endpoints (POST, PUT, PATCH) require the `X-Idempotency-Key` header. This client-generated key lets the API detect and deduplicate repeated requests.

```bash theme={"theme":"tokyo-night"}
curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/withdrawal \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'
```

### When it is required

The `X-Idempotency-Key` header is required on any request that creates or modifies a resource. GET and DELETE requests do not require it.

### Conflict behavior

If a request arrives with an idempotency key that was already used, the API returns HTTP `409 Conflict`:

```json theme={"theme":"tokyo-night"}
{
  "code": "IDEMPOTENT_ID_CONFLICT",
  "message": "A request with this idempotency key has already been processed.",
  "details": {}
}
```

## Examples

Generate a UUID v4 for each unique operation:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":"tokyo-night"}
    import uuid

    idempotency_key = str(uuid.uuid4())
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={"theme":"tokyo-night"}
    const idempotencyKey = crypto.randomUUID();
    ```
  </Tab>
</Tabs>

Retrying safely after a timeout:

```bash theme={"theme":"tokyo-night"}
# First attempt — times out
curl ... --header 'X-Idempotency-Key: 550e8400-...'

# Retry with the same key — safe, returns original result
curl ... --header 'X-Idempotency-Key: 550e8400-...'
```

<Warning>
  Never reuse an idempotency key for a different operation. Each unique operation must have its own key.
</Warning>