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 часа. После истечения срока тот же ключ будет обработан как новый.

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

Рекомендуемый паттерн: на каждое создание передавайте и 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_id409 DUPLICATE_ORDER_ID;
  • та же валюта, мягкий режим (allowDuplicateOrderId) — идемпотентно возвращается существующая заявка.

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

Сгенерируйте X-Idempotency-Key один раз на бизнес-операцию и переиспользуйте его при ретраях.

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

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 изолирован в пределах вашего сайта. Ключи разных сайтов не пересекаются.
Коды ошибок целиком — на странице Ошибки. Подпись запросов — Аутентификация.