# Idempotency key

> A unique request value that makes a retry return the first result instead of a duplicate. How the CryptoLike API uses Idempotency-Key, order_id and payout_id.

Source: https://cryptolike.net/glossary/idempotency-key
Updated: 2026-09-25

A unique value a client attaches to a request so that repeating it after a timeout or an error returns the first result instead of creating a duplicate.

## How it works in CryptoLike

The CryptoLike API accepts an `Idempotency-Key` header on every `POST`: up to 128 printable ASCII characters (`!` to `~`), for example your order ID. An empty or whitespace-only header counts as no header; a longer key or other characters answer `400 validation_error` for the field `Idempotency-Key`. A repeated request with the same key returns the original response with `Idempotent-Replayed: true`, and nothing is created twice. Keys are remembered for 24 hours per API key, so a retry within that window never creates a second payment or payout.

The repeat must be the same request — same method, path and body. A different body with the same key is `422 idempotency.mismatch`: use one key per logical operation. If the first request is still running, the answer is `409 idempotency.in_progress`: wait and repeat. Only responses below 400 are stored; an error releases the key, so a corrected retry runs again. After `504 timeout`, retry with the same key. The official SDKs add the header to every `POST` for you.

Two more guards work without the header. On `POST /v1/invoices`, `idempotency_by_order_id: true` returns the open payment of the same `order_id` instead of creating a second one. On `POST /v1/withdrawals`, your `payout_id` with the same coin, amount and address returns the existing withdrawal, while different parameters are `409` — a retry with the same `payout_id` does not pay twice. On the receiving side, a [webhook](https://cryptolike.net/glossary/webhook) handler deduplicates by `event_id`.

## Example

A CryptoLike payment request with an idempotency key: if the connection drops before the answer arrives, send the same request again — same key and body, signed afresh with a new timestamp at least one second later — and you get the same payment back. `$KEY_ID`, `$TS` and `$SIG` are the signing values from the [API authentication guide](https://cryptolike.net/docs/auth):

```bash
curl -s https://api.cryptolike.net/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-A-1001" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d '{"amount":"10.50","currency":"USD","order_id":"A-1001"}'
```