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

# Idempotency

> Ensure safe retries and prevent duplicate operations with idempotency keys

Idempotency lets you safely retry POST requests without creating duplicates. Send an `Idempotency-Key` header and Conduit will return the same response for identical retries.

## When to Use

Use an idempotency key whenever you might retry a request:

* Network timeouts or client restarts.
* Users double-clicking “submit”.
* Automatic retries from your job queue.

Currently, keys are honored on `POST /transactions`. Check each endpoint’s reference page as coverage expands.

## Make an Idempotent Request

```bash theme={null}
curl --request POST https://api.conduit.financial/transactions \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01" \
  --header "Idempotency-Key: unique-key-12345" \
  --data '{"type":"deposit","amount":"100.00","asset":"USD"}'
```

Guidelines:

* Generate a fresh key per operation (UUIDs or timestamp + intent work well).
* Reuse the same key only when retrying the same request payload.
* Keep keys ≤ 128 characters and store them on the client so you can retry with the original value.

## What Happens

1. Conduit processes the first request, stores the response, and returns it.
2. A retry with the same key and payload returns the cached response plus `Idempotency-Replayed: true`.

## Common Errors

* **422 Unprocessable Entity** – The same key was used with different payload data. Pick a new key.
* **409 Conflict** – Two identical requests arrived at the same time. Retry once the first finishes.
* **400 Bad Request** – Key longer than 128 characters; trim the value.

## Scoping Rules

Keys are unique per client. Two different clients can reuse the same value, but a single client cannot reuse a key for different operations.

## Retry Tips

Wrap idempotent calls in a retry helper that:

* Uses the same key for each retry attempt.
* Backs off when you receive `409 Conflict`.
* Switches to a new key only when the operation truly changes.