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

# Idempotency

> Retry card operations safely with the Idempotency-Key header.

Network errors happen. To retry a request without doing the work twice, send an `Idempotency-Key` header.

```bash theme={null}
curl -X POST https://api.stablemesh.io/v1/card/deposit \
  -H "X-API-KEY: smk_live_..." \
  -H "Idempotency-Key: 6c0a3c8e-1f7b-4f53-9d77-0b8e2a1c4d5f" \
  -H "Content-Type: application/json" \
  -d '{"cardId": "2026100117908000004821", "amount": "100"}'
```

***

## How it works

* The **first** request with a key runs normally, and its response is stored.
* A **retry** with the same key and the same body returns the stored response. It does not run again. The replayed response carries the header `Idempotent-Replayed: true`.
* Reusing a key with a **different** body is refused with HTTP `409`, code `4211`.
* If the first request is **still running**, a retry is refused with HTTP `409`, code `4212`. Wait, then retry.

Keys are scoped to your account and can be up to 255 characters. Use a new UUID for each operation.

***

## Supported endpoints

`Idempotency-Key` applies to the endpoints that move money or change a card:

* `card/create`
* `card/deposit`
* `card/withdraw`
* `card/freeze`
* `card/unfreeze`
* `card/cancel`

Other endpoints ignore it. Reads are always safe to repeat.

<Info>
  An internal error (`9999`) is also stored. If its outcome is unknown, check the card or withdrawal state first, and then retry with a **new** key if needed.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.