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

# Idempotency

> Safely retry mutating API requests with Idempotency-Key headers.

Network timeouts and client retries can cause duplicate operations. Remitflex idempotency lets you retry mutating requests safely when authenticated with an **API key**.

## When idempotency is required

| Auth method   | Mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) |
| ------------- | ---------------------------------------------------- |
| API key       | **Required** — include `Idempotency-Key`             |
| Dashboard JWT | Not required                                         |

## Header

```
Idempotency-Key: 7f3c2a1b-4e5d-6c7b-8a9f-0e1d2c3b4a5f
```

* Max length: **255 characters**
* Use a fresh UUID (or similar unique string) per distinct operation
* TTL: **24 hours** (configurable server-side via `IDEMPOTENCY_TTL_SECONDS`)

## Behavior

1. First request with a given key → processed normally; response cached in Redis.
2. Retry with the **same** key, org, HTTP method, and path → cached response returned without re-executing.
3. Different operation → use a **new** idempotency key.

<Warning>
  Reusing an idempotency key for a different request body returns the original response. Always generate a new key per operation.
</Warning>

## Example: create payment route

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.remitflex.io/v1/payment-routes \
    -H "Authorization: Bearer $REMITFLEX_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Supplier collection",
      "originChainKey": "tron",
      "destinationChainKey": "base",
      "destinationCurrency": "USDC",
      "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }'
  ```

  ```javascript JavaScript theme={null}
  import { randomUUID } from "crypto";

  const res = await fetch("https://api.remitflex.io/v1/payment-routes", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REMITFLEX_API_KEY}`,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Supplier collection",
      originChainKey: "tron",
      destinationChainKey: "base",
      destinationCurrency: "USDC",
      destinationAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    }),
  });
  ```

  ```python Python theme={null}
  import os, uuid, requests

  requests.post(
      "https://api.remitflex.io/v1/payment-routes",
      headers={
          "Authorization": f"Bearer {os.environ['REMITFLEX_API_KEY']}",
          "Idempotency-Key": str(uuid.uuid4()),
      },
      json={
          "name": "Supplier collection",
          "originChainKey": "tron",
          "destinationChainKey": "base",
          "destinationCurrency": "USDC",
          "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      },
  )
  ```
</CodeGroup>

## Endpoints that require idempotency (API key)

All `POST` and `DELETE` endpoints in this reference, including:

* `POST /customers`
* `POST /payment-routes`, `POST /payment-routes/{paymentRouteId}/deposits/sync`, `DELETE /payment-routes/{paymentRouteId}`

## Errors

| Code  | Message                                                        |
| ----- | -------------------------------------------------------------- |
| `400` | `Idempotency-Key header is required for mutating API requests` |
| `422` | `Idempotency-Key must be 255 characters or fewer`              |

Failed requests are **not** cached — safe to retry with the same key after fixing the error.