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

# Idempotency

> Use idempotency keys to safely retry requests without creating duplicate transactions or resources.

Network failures and timeouts are unavoidable. When a request to create a transaction or account times out, you cannot know whether the server processed it before the connection dropped. Without a mechanism to safely retry, you risk creating duplicate payments or records.

Thiqwave supports **idempotency keys** to solve this problem. When you include an `Idempotency-Key` header on a supported request, Thiqwave stores the result of that request and returns the **same response** for any subsequent request made with the same key — without executing the operation a second time.

***

## How to Use Idempotency Keys

Add the `Idempotency-Key` header to your request with a unique string value. A **UUID v4** is the recommended format.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/transactions \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
    -d '{
      "amount": 5000,
      "currency": "AED",
      "recipient_account_id": "acct_01hx9z3k2p",
      "reference": "INV-2026-0042"
    }'
  ```

  ```javascript JavaScript theme={null}
  const { randomUUID } = require("crypto");

  const idempotencyKey = randomUUID();

  const response = await fetch("https://api.thiqwave.com/v1/transactions", {
    method: "POST",
    headers: {
      "X-API-Key": "your-api-key",
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      amount: 5000,
      currency: "AED",
      recipient_account_id: "acct_01hx9z3k2p",
      reference: "INV-2026-0042",
    }),
  });

  const data = await response.json();
  ```

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

  idempotency_key = str(uuid.uuid4())

  headers = {
      "X-API-Key": "your-api-key",
      "Content-Type": "application/json",
      "Idempotency-Key": idempotency_key,
  }

  payload = {
      "amount": 5000,
      "currency": "AED",
      "recipient_account_id": "acct_01hx9z3k2p",
      "reference": "INV-2026-0042",
  }

  response = requests.post(
      "https://api.thiqwave.com/v1/transactions",
      headers=headers,
      json=payload,
  )
  data = response.json()
  ```
</CodeGroup>

***

## Supported Endpoints

The following endpoints support idempotency keys:

| Endpoint                  | Description                       |
| ------------------------- | --------------------------------- |
| `POST /v1/transactions`   | Initiate a payment or transfer    |
| `POST /v1/accounts`       | Create a new business account     |
| `POST /v1/compliance/kyb` | Submit a KYB verification request |

Idempotency keys have no effect on `GET`, `PATCH`, or `DELETE` requests — those operations are either read-only or naturally safe to repeat.

***

## How It Works

When you send a request with an `Idempotency-Key`:

1. Thiqwave checks whether a request with that key has already been processed.
2. If **no prior request** exists with that key, the request is executed normally and the result is stored against the key.
3. If a **matching request** already exists, Thiqwave returns the stored response immediately — the operation is not executed again.

Stored results are retained for **24 hours** from the time of the original request. After that, the key expires and can be reused (though reusing keys is not recommended).

***

## Conflict Response

If you send the same `Idempotency-Key` with a **different request body**, Thiqwave returns a `409 Conflict` error:

```json theme={null}
{
  "error": "Conflict",
  "message": "An idempotency key conflict was detected. The provided key was previously used with a different request body.",
  "code": "IDEMPOTENCY_CONFLICT"
}
```

This protects you from accidentally overwriting the result of a previous operation. If you receive a `409` due to a key conflict, generate a new key and resubmit only if you intend to create a new, separate operation.

***

## Best Practices

* **Generate one key per operation, not per session.** Each distinct operation (e.g. each payment) should have its own unique key. Do not reuse a key for a second, unrelated request.
* **Use UUID v4.** It is statistically unique, widely supported, and trivial to generate in any language.
* **Store the key alongside your operation record.** Before sending a request, persist the idempotency key to your database. This allows you to retry with the exact same key if the request times out, and to correlate the result with your internal records.
* **Do not retry on `4xx` errors other than `429`.** If a request fails with a validation error (`422`), fix the payload and generate a **new** idempotency key — retrying with the original key and a corrected payload will result in a `409 Conflict`.