Рецепт устойчивого клиента

Сеть ненадёжна, а вы работаете с деньгами. Эта инструкция — про то, как построить клиент, который переживает таймауты, повторы и временные сбои, не создавая дублей и не теряя платежи. Здесь сведены воедино идемпотентность, обработка таймаутов, ретраи и backoff.

Справочная база — Идемпотентность и Формат ответа и коды ошибок.

---

​

Главный принцип

Каждый денежный запрос отправляйте с заголовком Idempotency-Key. Тогда любой повтор безопасен.

Это фундамент всей устойчивости. Без защиты от дублей повтор при таймауте = второй счёт или вторая выплата. С ней повтор = тот же объект. Всё остальное в этой инструкции опирается на это правило.

​

Два механизма, а не один

Дедупликацию дают два независимых механизма. Они работают вместе, и лучше использовать оба.

	HTTP‑заголовок Idempotency-Key	Поле order_id
Что это	Технический ключ одной попытки действия	Ваш бизнес‑идентификатор (заказ, выплата)
Уровень	Транспорт: любой запрос	Данные: платежи, выплаты, возвраты
Значение	Любое уникальное, ≤255 символов (обычно UUID)	Ваш номер заказа
Когда генерируется	До первой отправки, одинаков во всех попытках	Когда появился заказ
Что вернёт повтор	Тот же ответ + заголовок Idempotent-Replayed: true	Тот же объект
Обязателен?	Нет, но настоятельно рекомендуется	Для выплат — обязателен

Ключевое правило заголовка: значение генерируется один раз, до первой отправки, и остаётся тем же во всех ретраях этого действия. Если вы сгенерируете новый ключ на каждую попытку — защиты не будет вовсе, вы просто отправите N разных запросов.

Python

import uuid

key = str(uuid.uuid4())          # ОДИН РАЗ на действие — не внутри цикла ретраев!

for attempt in range(5):
    resp = call("/v1/payout", {
        "amount": "25", "currency": "USDT", "network": "tron",
        "address": "TXY...", "order_id": "payout-1",
    }, idempotency_key=key)      # ТОТ ЖЕ ключ во всех попытках
    ...

const key = crypto.randomUUID();     // ОДИН РАЗ на действие — не внутри цикла ретраев!

for (let attempt = 0; attempt < 5; attempt++) {
  const resp = await call("/v1/payout", {
    amount: "25", currency: "USDT", network: "tron",
    address: "TXY...", order_id: "payout-1",
  }, key);                           // ТОТ ЖЕ ключ во всех попытках
  // ...
}

Чтобы передать заголовок, добавьте его в свою обёртку call() (базовая версия — в инструкции Как подписать запрос):

Python

def call(path: str, payload: dict, idempotency_key: str | None = None) -> dict:
    body = json.dumps(payload, separators=(",", ":"))
    ts = str(int(time.time()))
    signing = f"{ts}\nPOST\n{path}\n{body}"
    sig = hmac.new(SECRET, signing.encode(), hashlib.sha256).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-Public-Id": PUBLIC_ID,
        "X-Timestamp": ts,
        "X-Signature": sig,
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key   # ← в подпись НЕ входит
    return requests.post(BASE + path, data=body, headers=headers).json()

async function call(path, payload, idempotencyKey = null) {
  const body = JSON.stringify(payload);
  const ts = Math.floor(Date.now() / 1000).toString();
  const signing = `${ts}\nPOST\n${path}\n${body}`;
  const sig = crypto.createHmac("sha256", SECRET).update(signing).digest("hex");
  const headers = {
    "Content-Type": "application/json",
    "X-Public-Id": PUBLIC_ID,
    "X-Timestamp": ts,
    "X-Signature": sig,
  };
  if (idempotencyKey) {
    headers["Idempotency-Key"] = idempotencyKey;   // ← в подпись НЕ входит
  }
  const res = await fetch(BASE + path, { method: "POST", headers, body });
  return res.json();
}

Заголовок Idempotency-Key не участвует в подписи — подписывается только каноническая строка ts\nMETHOD\npath\nbody. Добавление заголовка ничего не ломает в подписи.

​

Что делать, если заголовок ещё не внедрён

order_id тоже дедуплицирует — это ваша страховка. Если вы не готовы менять транспортный слой, минимум остаётся прежним: всегда задавайте order_id, и повтор вернёт существующий объект.

Опасен только случай, когда нет ни того, ни другого: без заголовка и без order_id повтор создаст дубль. Для выплат это невозможно (order_id обязателен), для платежей — вполне.

---

​

Проблема таймаута: «ответ не пришёл — операция прошла или нет?»

Самая коварная ситуация. Вы отправили POST /v1/payout, но ответ не дошёл (таймаут, разрыв). Выплата могла:

• не создаться — запрос не дошёл до сервера;
• создаться — сервер обработал, но ответ потерялся по пути к вам.

Гадать нельзя. Правильных действий два, и оба безопасны благодаря идемпотентности:

​

Вариант А. Повторить тот же запрос

Повторяйте с тем же Idempotency-Key и тем же order_id:

Python

# Повтор идемпотентен: если выплата уже создана — вернётся ОНА, дубля не будет
result = call("/v1/payout", {
    "amount": "25", "currency": "USDT", "network": "tron",
    "address": "TXY...", "order_id": "payout-1",   # ТОТ ЖЕ order_id
}, idempotency_key=key)                            # ТОТ ЖЕ Idempotency-Key

// Повтор идемпотентен: если выплата уже создана — вернётся ОНА, дубля не будет
const result = await call("/v1/payout", {
  amount: "25", currency: "USDT", network: "tron",
  address: "TXY...", order_id: "payout-1",   // ТОТ ЖЕ order_id
}, key);                                     // ТОТ ЖЕ Idempotency-Key

Если первая попытка прошла — получите ту же выплату (в ответе будет Idempotent-Replayed: true). Если не прошла — создастся сейчас. В обоих случаях итог один, и денег не уйдёт дважды.

409 idempotency.in_progress означает, что запрос с этим ключом прямо сейчас выполняется на сервере. Это не ошибка и не отказ: подождите и повторите — получите результат первой попытки.

​

Вариант Б. Спросить статус

Python

# Узнать, что с выплатой по вашему order_id
info = call("/v1/payout/info", {"order_id": "payout-1"})
# 404 payout.not_found → не создавалась, можно создавать
# объект выплаты → уже существует, действуйте по её статусу

// Узнать, что с выплатой по вашему order_id
const info = await call("/v1/payout/info", { order_id: "payout-1" });
// 404 payout.not_found → не создавалась, можно создавать
// объект выплаты → уже существует, действуйте по её статусу

Для платежей — /v1/payment/info, для выплат — /v1/payout/info.

---

​

Почему подписи недостаточно

Подпись запроса живёт в окне ±5 минут — она гасит переигрывание запроса старше пяти минут, но не защищает от повторной обработки внутри окна. Реальную защиту от дублей дают Idempotency-Key и order_id, а не подпись. Не полагайтесь на подпись как на защиту от двойного списания. → Аутентификация

---

​

Какие ошибки повторять, а какие — нет

Класс	Коды	Повторять?	Как
Ваша ошибка запроса	400 *, большинство 403	Нет	Исправить запрос; повтор даст тот же результат.
Аутентификация	401 *	Нет	Починить подпись/часы/ключ.
Не найдено	404 *	Нет	Проверить идентификатор.
Конфликт состояния	409 *	Смотря какой	Не считайте любой 409 финальным — см. ниже.
Временная недоступность	503, 429-подобная	Да	Экспоненциальный backoff.
Внутренняя	500	Да	Экспоненциальный backoff.

​

Не все 409 финальны

Самая дорогая ошибка в клиенте: трактовать любой 409 как финал и бросить операцию. Так вы потеряете законную выплату. Среди 409 есть ретраибельные:

Код 409	Повторять?	Почему
payout.funds_maturing	ДА, позже	Средства ещё дозревают. Пройдут подтверждения — выплата пройдёт.
idempotency.in_progress	ДА, позже	Запрос с этим Idempotency-Key ещё выполняется.
payout.frozen	ДА, позже	Сработал kill‑switch, защита временная.
payout.insufficient_funds	Нет	Денег реально не хватает — нужно пополнение, а не ожидание.
Прочие 409	Не вслепую	Сверьтесь через */info.

Полный список кодов — Справочник кодов ошибок.

---

​

Особый случай: 409 payout.funds_maturing

Это не повод отказаться от выплаты навсегда. Средства ещё дозревают (см. Модель баланса). Это временно: повторите позже с backoff — когда депозит наберёт подтверждения, выплата пройдёт. Не путайте с 409 payout.insufficient_funds (реально не хватает денег — нужно пополнение, а не ожидание).

---

​

Экспоненциальный backoff

Для 5xx/503/rate limit повторяйте с растущей задержкой, а не в цикле без пауз.

Ключевая идея: повторять надо по HTTP‑статусу (429/5xx) и по сетевым сбоям, а не только по error.code. Здесь signed_post / signedPost — ваш POST с подписью, возвращающий сырой ответ (requests.Response в Python, Response из fetch в Node.js — в отличие от call(), который отдаёт уже разобранное тело), чтобы был виден статус и заголовок Retry-After.

Python

import time, random, requests, uuid

RETRIABLE_HTTP = {429, 500, 502, 503, 504}   # временные статусы
# ретраибельные бизнес-коды, приходящие с 4xx (в основном 409) — их НЕЛЬЗЯ хоронить
RETRIABLE_CODES = {"payout.funds_maturing", "idempotency.in_progress", "payout.frozen"}

def call_resilient(path, payload, max_attempts=6):
    delay = 1.0
    last = None
    key = str(uuid.uuid4())      # ОДИН ключ на все попытки этого действия
    for _ in range(max_attempts):
        try:
            # signed_post кладёт key в заголовок Idempotency-Key
            resp = signed_post(path, payload, idempotency_key=key)   # → requests.Response
        except requests.RequestException:
            # сетевой сбой/таймаут — временно, повторяем (идемпотентность по order_id спасает от дублей)
            time.sleep(delay); delay = min(delay * 2, 60) + random.uniform(0, 0.5); continue

        last = resp
        if 200 <= resp.status_code < 300:        # успех
            return resp.json()

        if resp.status_code in RETRIABLE_HTTP:    # временный статус
            wait = float(resp.headers.get("Retry-After", delay))   # уважаем Retry-After (напр. 429)
            time.sleep(min(wait, 60))
            delay = min(delay * 2, 60) + random.uniform(0, 0.5)
            continue

        # прочие 4xx — не повторяем; ИСКЛЮЧЕНИЕ — ретраибельные бизнес-коды (в т.ч. 409!)
        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        if body.get("error", {}).get("code") in RETRIABLE_CODES:
            time.sleep(delay); delay = min(delay * 2, 60) + random.uniform(0, 0.5); continue

        return body   # окончательная ошибка запроса — повтор не поможет

    if last is None:
        return None
    try:
        return last.json()
    except ValueError:            # не-JSON тело (напр., HTML от прокси на 502)
        return None

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const RETRIABLE_HTTP = new Set([429, 500, 502, 503, 504]);
// ретраибельные бизнес-коды, приходящие с 4xx (в основном 409)
const RETRIABLE_CODES = new Set([
  "payout.funds_maturing", "idempotency.in_progress", "payout.frozen",
]);

// signedPost — ваша подписанная обёртка, возвращающая СЫРОЙ fetch-Response
// (а не разобранный JSON), чтобы был виден HTTP-статус и заголовки. См.
// «Как подписать запрос» (пример на Node.js).
async function callResilient(path, payload, maxAttempts = 6) {
  let delay = 1000;
  let last = null;
  const key = crypto.randomUUID();      // ОДИН ключ на все попытки этого действия
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    let resp;
    try {
      resp = await signedPost(path, payload, { idempotencyKey: key }); // → заголовок Idempotency-Key
    } catch (e) {                              // сетевой сбой/таймаут — повторяем
      await sleep(delay);
      delay = Math.min(delay * 2, 60000) + Math.random() * 500;
      continue;
    }
    last = resp;

    if (resp.ok) return await resp.json();     // 2xx — успех

    if (RETRIABLE_HTTP.has(resp.status)) {     // 429 + 5xx — временное, ждём и повторяем
      const ra = parseFloat(resp.headers.get("Retry-After"));  // у 429 приходит Retry-After: 60
      await sleep(Number.isFinite(ra) ? Math.min(ra * 1000, 60000) : delay);
      delay = Math.min(delay * 2, 60000) + Math.random() * 500;
      continue;
    }

    // Прочее (4xx) — постоянная ошибка запроса, повтор не поможет.
    const body = await resp.json().catch(() => ({}));
    if (RETRIABLE_CODES.has(body.error?.code)) {  // ИСКЛЮЧЕНИЕ: ретраибельные 409
      await sleep(delay);
      delay = Math.min(delay * 2, 60000) + Math.random() * 500;
      continue;
    }
    return body;
  }
  return last ? await last.json().catch(() => null) : null;
}

Почему по HTTP-статусу, а не по error.code? Ответ 429 приходит в особом виде {"state":1,"message":"rate limit exceeded"} — без error.code, поэтому ветвиться на код бесполезно: 429 надо ловить именно по статусу и читать заголовок Retry-After.

Джиттер (случайная добавка к задержке) важен: без него много клиентов после сбоя ударят одновременно. Потолок задержки не даёт ретраям растягиваться бесконечно.

---

​

Практические правила

• Idempotency-Key генерируется до первой отправки и не меняется при ретраях. Новый ключ на каждую попытку = никакой защиты.
• order_id уникален и стабилен на операцию. Один заказ → один order_id, и при ретраях — тот же. Не генерируйте новый на каждую попытку.
• Таймаут не равен провалу. Прежде чем считать операцию неудачной, повторите тот же запрос (тот же Idempotency-Key и order_id) или спросите */info.
• 409 — не повторяйте вслепую, но и не хороните. payout.funds_maturing, idempotency.in_progress, payout.frozen — повторяйте позже; остальные — сначала выясните состояние через */info.
• Разделяйте временное и постоянное. 5xx/503/429/funds_maturing — ждите и повторяйте; 4xx — чините запрос.
• Храните сопоставление order_id ↔ ваш заказ на своей стороне — это ваш якорь для сверки после любого сбоя.
• Ограничьте число попыток и логируйте исчерпание — бесконечный ретрай маскирует реальные проблемы.

---

​

Как это сочетается с вебхуками

Ретраи касаются исходящих запросов. Для входящих вебхуков действует зеркальный принцип: они доставляются at-least-once, поэтому ваш обработчик тоже должен быть идемпотентным (дедуп по uuid + status). Устойчивость нужна с обеих сторон. → Настройка вебхуков

---

​

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

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

Формат ответа и коды ошибок

Справочник кодов ошибок

Модель баланса

Настройка вебхуков

Чек‑лист перед запуском