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

# Idempotency

> Safe retries with the Idempotency-Key header

Mutating endpoints (`POST`, `PATCH`, `DELETE`) accept an optional `Idempotency-Key` header. When you supply one, the server caches the response for 24 hours and replays it verbatim on retries — so a network timeout or process crash can't cause a duplicate payment link, session, or webhook endpoint.

```http theme={null}
POST /api/v1/checkout_sessions
Authorization: Bearer ck_live_...
Idempotency-Key: order-123-checkout-v1
Content-Type: application/json
```

## Key requirements

* **Unique per request** — use a value tied to the operation, not a random UUID you generate on every retry. A good pattern: `{orderId}-{operation}-{version}`.
* **String, any format** — up to 255 characters.
* **Scope** — idempotency is scoped per API key. The same key used by two different API keys is treated as two independent operations.

## Replay behavior

When the server returns a cached response, the reply includes the header:

```http theme={null}
Idempotent-Replayed: true
```

The status code and body are identical to the original response.

## Conflict: different body, same key

If you send the same `Idempotency-Key` with a different request body, you get a `409 conflict`:

```json theme={null}
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "Idempotency-Key already used with a different request body",
    "requestId": "req_..."
  }
}
```

This is a guard against accidental key reuse. If you hit this, either fix the key or use a new one.

## When to use it

Always use `Idempotency-Key` for operations where duplicates matter:

* Creating a checkout session for a specific order
* Creating a payment link for a product
* Creating a webhook endpoint during setup

You can omit it for exploratory reads or one-off operations where duplicates are harmless.