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

# Idempotency

> Ensure safe retries and prevent duplicates using the Idempotency-Key header.

We support **idempotent requests** to help you retry safely without creating duplicates. This is especially important for actions like **creating payments**, **modifying data**, or **submitting forms**, where repeated requests could otherwise result in undesired side effects.

## What Is Idempotency?

Idempotency ensures that performing the **same request multiple times** has the **same effect** as performing it once.

If your client experiences a timeout or network error, you can retry the request using the **same idempotency key**, and we will ensure it is only processed **once**.

## How It Works

To make an idempotent request, include a unique key in the header:

`Idempotency-Key: your-unique-idempotency-key`

We store the **status code and response body** of the first request associated with that key. Any subsequent request with the same key:

* Returns the **original result**, regardless of success or failure
* Prevents **duplicate processing** of resource creation or updates
* Maintains **data integrity** across retries

This behavior applies even if the first request resulted in a `500` or other server error, ensuring consistency regardless of outcome.

<Note>`Idempotency-Key` in `GET` or `DELETE` requests is ignored.</Note>

## Key Expiration

* Idempotency keys are stored for **24 hours**.
* After expiration, reusing the same key is treated as a **new request**.
* Keys are **up to 255 characters long**.

## Response Headers

To help clients verify how an idempotent request was handled, we include the following response headers whenever an `Idempotency-Key` is used:

| Header               | Description                                                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key`    | Echoes the key used in the request, confirming it was recognized and applied                                                                         |
| `Idempotency-Status` | Indicates how the request was processed:<br />`new` – First execution of the key<br />`replayed` – Cached response from an earlier identical request |

Example:

```
HTTP/1.1 200 OK
Idempotency-Key: 6aa2f8a3-4ef4-4899-8234-d45a93d1f191
Idempotency-Status: replayed
```

These headers are useful for debugging retries and understanding whether a result was replayed or newly generated.

## Best Practices

* Use a **UUIDv4** or another random, high-entropy string to generate keys.
* **Only reuse a key** if retrying the **same exact request**.
* **Never use the same key** for different operations, endpoints, or payloads.

<Note>BitGPT will reject repeat requests with the same key if the **parameters differ** from the original, to prevent accidental misuse.</Note>

## When to Use Idempotency

Idempotency is recommended for any request where duplication would have negative effects, including:

* Creating payments, invoices, or subscriptions
* Modifying product or user data
* Sending webhooks or external callbacks
* Initiating long-running or asynchronous tasks

## Summary

| Header            | Required                                                         | Description                                                            |
| ----------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `Idempotency-Key` | Optional (but recommended for all `POST`/`PUT`/`PATCH` requests) | Ensures that a given operation is only performed once, even if retried |

BitGPT’s idempotency layer **does not cache invalid requests** — if a request fails validation or is rejected before execution, the key will not be stored. You are free to retry those requests.

Need implementation help or debugging assistance? Reach out to [support@bitgpt.xyz](mailto:support@bitgpt.xyz) and include your request payload and idempotency key.