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

# Идемпотентность

Повторный вызов создающего эндпоинта **не должен создавать второй объект**. Иначе обычный сетевой
таймаут (ответ потерялся, хотя платёж уже создан) обернётся дублем — вторым счётом или второй выплатой.

Защититься можно двумя способами — они работают вместе.

## 1. Заголовок `Idempotency-Key` (рекомендуемый)

Как пользоваться:

* **Значение** — любая уникальная строка **до 255 символов** (обычно UUID v4). Сгенерируйте его **до первой отправки** запроса и передавайте **одно и то же** во всех повторах одного действия. Новое действие — новый ключ.
* **Где работает** — на всех создающих операциях: платёж, выплата, возврат, статический кошелёк, перевод, батч.
* **Поведение повтора** — повтор с тем же ключом вернёт **тот же ответ**, что и первая успешная попытка (второй объект не создаётся), и заголовок ответа `Idempotent-Replayed: true` — по нему видно, что это переигранный результат, а не новая операция.

```bash theme={null}
curl -X POST https://api.oblodai.com/v1/payment \
  -H "Idempotency-Key: 3f2a9c6e-8d41-4b7a-9c05-1e6f2b8d4a70" \
  ...
```

## 2. Ваш `order_id`

Второй, бизнес-уровень дедупликации — он работает, даже если заголовок забыли:

* **Платежи** — `order_id` необязателен, но настоятельно рекомендуется. Повтор с `order_id`, для которого уже есть **живой** счёт, вернёт этот же счёт, а не создаст дубль (терминальный или просроченный счёт создание нового не блокирует). Проверка-и-создание защищены advisory-локом по паре `(мерчант, order_id)` от гонки одновременных запросов.
* **Выплаты** — `order_id` **обязателен** (без него — `400 payout.order_id_required`). Идемпотентность по `(мерчант, order_id)`: повтор вернёт уже созданную выплату.

Механизмы независимы и работают вместе: `order_id` дедуплицирует на уровне бизнес-сущности, а заголовок `Idempotency-Key` защищает сам HTTP-вызов. Заголовок поддерживают: `POST /v1/payment`, `/v1/payment/refund`, `/v1/payment/resolve`, `/v1/payment/batch`, `/v1/refund/batch`, `/v1/payout`, `/v1/payout/mass`, `/v1/payout/batch`, `/v1/transfer/to-personal`. На [выплатных ссылках](/reference/payout-link) заголовок не действует — там дедупликация через поле `reference`.

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Устойчивый клиент" href="/guides/resilient-client" icon="arrow-right" horizontal />

  <Card title="Создание платежа" href="/reference/payment-create" icon="arrow-right" horizontal />

  <Card title="Создание выплаты" href="/reference/payout-create" icon="arrow-right" horizontal />

  <Card title="Формат запросов" href="/reference/basics-format" icon="arrow-right" horizontal />
</CardGroup>