Skip to main content
Сетевые сбои неизбежны: вы отправили POST, не получили ответа и не знаете, дошёл ли он. Идемпотентность гарантирует, что безопасный повтор не создаст вторую заявку. На платформе для этого есть два независимых механизма — их можно использовать вместе.
Примеры используют единый стиль: базовый URL https://wallet.your-exchange.com, order_id вида INV-2026-000042. Подпись запросов — на странице Аутентификация.

​
Два механизма

order_id — это ваш собственный идентификатор заявки. Вы передаёте его при создании депозита или выплаты, а затем по нему находите ресурс через GET .../by-order-id/{order_id}.По умолчанию действует строгий режим. order_id должен быть уникальным в рамках всего сайта — это общий номер на все валюты, а не отдельный счётчик на каждый актив. Повторный POST с уже использованным order_id вернёт 409 DUPLICATE_ORDER_ID. В том числе если вы попробуете тот же order_id с другим активом (assetCode) — переиспользовать номер на другой валюте нельзя, это всегда 409.Строгий режим — это защита от случайной двойной заявки. Для безопасных повторов он не предназначен: используйте X-Idempotency-Key (ниже).Оператор может включить для вашего сайта мягкий режим (allowDuplicateOrderId). В нём повтор с тем же order_id и тем же активом идемпотентно вернёт существующую заявку вместо 409. Если вы полагаетесь на это поведение — уточните режим у оператора.Если order_id не передан, платформа сгенерирует уникальный код автоматически (формат NNNN-NNNN-NNNN). Авто-сгенерированные коды всегда уникальны, поэтому каждый такой вызов создаёт новую заявку.
Заголовок X-Idempotency-Key: <uuid> на write-операциях. Первый запрос с этим ключом выполняется и его результат сохраняется. Любой повтор с тем же ключом возвращает тот же сохранённый результат — без выполнения операции, без дубликата и без 409, независимо от режима order_id.Ключ изолирован в пределах вашего сайта (другие сайты не видят и не пересекаются с вашими ключами) и хранится 24 часа. После истечения срока тот же ключ будет обработан как новый.

​
Когда что использовать

СценарийМеханизм
Привязать заявку платформы к заявке в вашей CMSorder_id
Найти ранее созданный депозит/выплатуGET .../by-order-id/{order_id}
Не допустить случайной второй заявки на один заказorder_id (строгий режим)
Безопасно повторить запрос после таймаута/сетевой ошибкиX-Idempotency-Key
Рекомендуемый паттерн: на каждое создание передавайте и order_id (как бизнес-ключ заявки), и X-Idempotency-Key (как технический ключ повтора). Тогда повтор после сбоя вернёт исходный результат, а не упрётся в 409 DUPLICATE_ORDER_ID.

​
Что считается «повтором»

X-Idempotency-Key сопоставляет запросы по самому ключу. Первый запрос с данным ключом фиксирует результат на 24 часа; все последующие запросы с этим же ключом получают тот же сохранённый ответ — содержимое их тела при этом повторно не исполняется.
Один X-Idempotency-Key — для одного и того же запроса. Если переслать тот же ключ с другим телом, операция не выполнится: вы получите назад результат первого запроса. Для нового, по-настоящему другого запроса всегда генерируйте новый UUID.
order_id сопоставляется иначе — по бизнес-правилу уникальности в рамках сайта:
  • тот же order_id на другой валюте — всегда 409 DUPLICATE_ORDER_ID;
  • та же валюта, строгий режим (по умолчанию), явно переданный order_id — 409 DUPLICATE_ORDER_ID;
  • та же валюта, мягкий режим (allowDuplicateOrderId) — идемпотентно возвращается существующая заявка.

​
Пример: безопасный повтор

Сгенерируйте X-Idempotency-Key один раз на бизнес-операцию и переиспользуйте его при ретраях. 
import crypto from 'node:crypto';

// Один UUID на одну бизнес-операцию. При ретраях НЕ меняем его.
const idempotencyKey = crypto.randomUUID();

const rawBody = JSON.stringify({
  assetCode: 'USDT_TRC20',
  orderId: 'INV-2026-000042',
  expectedAmount: '100.50',
});

async function createDeposit() {
  const ts = Math.floor(Date.now() / 1000).toString();
  const signature = crypto
    .createHmac('sha256', process.env.WALLET_API_SECRET)
    .update(`${ts}.${rawBody}`)
    .digest('hex');

  return fetch('https://wallet.your-exchange.com/v1/public/deposits', {
    method: 'POST',
    headers: {
      'X-Api-Id': 'pk_live_a1b2c3d4',
      'X-Timestamp': ts,
      'X-Signature': signature,
      'X-Idempotency-Key': idempotencyKey, // одинаковый на всех попытках
      'Content-Type': 'application/json',
    },
    body: rawBody,
  });
}

// Повтор после сетевой ошибки вернёт ИСХОДНУЮ заявку, а не создаст новую.
let res = await createDeposit().catch(() => null);
if (!res || !res.ok) res = await createDeposit();

​
Рекомендации по ретраям

1

Фиксируйте X-Idempotency-Key до первой отправки

Сгенерируйте UUID, сохраните его рядом с заявкой и используйте на всех попытках одного и того же запроса. Не генерируйте новый ключ на каждый ретрай.
2

Повторяйте с задержкой

При таймаутах и ошибках 5xx используйте экспоненциальную задержку. На каждой попытке шлите тот же X-Idempotency-Key и то же тело.
3

Свежий X-Timestamp на каждой попытке

Подпись зависит от времени, а окно — ±300 секунд. Для каждой попытки берите актуальный X-Timestamp и заново вычисляйте X-Signature. Ключ идемпотентности при этом не меняется.
4

Сомневаетесь, прошёл ли запрос — проверьте по order_id

Если ретраи исчерпаны, выполните GET .../by-order-id/{order_id} — так вы узнаете, была ли заявка создана, не рискуя дублем.
X-Idempotency-Key хранится 24 часа. Для повторов после длительного простоя полагайтесь на order_id: в строгом режиме он по-прежнему не даст создать вторую заявку (вернёт 409 DUPLICATE_ORDER_ID), а вы сможете найти существующую через by-order-id.

​
Частые вопросы

В строгом режиме (по умолчанию) повтор с уже использованным order_id намеренно отклоняется — это защита от двойной заявки. Для безопасных ретраев добавьте X-Idempotency-Key: тогда повтор вернёт исходную заявку без 409.
Нет. order_id уникален в рамках всего сайта, общий на все активы. Тот же номер с другим assetCode всегда даёт 409 DUPLICATE_ORDER_ID.
Вернётся результат первого запроса с этим ключом. Операция с новым телом не выполнится. Для другого запроса всегда генерируйте новый UUID.
Нет. X-Idempotency-Key изолирован в пределах вашего сайта. Ключи разных сайтов не пересекаются.
Коды ошибок целиком — на странице Ошибки. Подпись запросов — Аутентификация.