Документация/Начало/Идемпотентность

Идемпотентность и повторы

Сетевой таймаут не означает, что операция не выполнилась. Правильный повтор — единственное, что отделяет неизвестный результат от второго списания.

Idempotency-Key

Заголовок обязателен для каждого POST и хранится не менее 48 часов в пределах вашего API-ключа. Одна бизнес-операция — это один order_id, одно неизменное тело запроса и один Idempotency-Key.

Повтор с тем же ключом и тем же телом возвращает сохранённый ответ и заголовок Idempotent-Replayed: true — новая операция не создаётся.

Как повторять

Повтор — это новая сетевая попытка той же операции, а не повторная отправка того же HTTP-запроса. Неизменными остаются метод, URL, тело, order_id и Idempotency-Key. Заново вычисляются:

  • X-Timestamp — иначе запрос выйдет за окно в 300 секунд;
  • X-Nonce — новый UUID на каждую попытку;
  • X-Signature — подпись считается от новой канонической строки.
# один Idempotency-Key на бизнес-операцию, новая подпись на каждую попытку
idem_key = f"create-{order_id}"
for attempt in range(5):
    ts = now_unix()
    nonce = uuid4()
    sig = hmac_sha256(secret, canonical(method, path, ts, nonce, idem_key, sha256(body)))
    res = send(method, path, body, ts, nonce, sig, idem_key)
    if res.status < 500 and res.status not in (429,):
        break
    sleep(backoff(attempt) + jitter())

Никогда не выдавайте новый ключ на неизвестный результат

Если исход финансовой операции неизвестен, повторяйте с тем же Idempotency-Key или запрашивайте статус. Новый ключ для той же операции — это второе списание.

Конфликты

  • Тот же ключ с другим телом — 409 idempotency_conflict. Это защита: платформа отказывается считать два разных запроса одной операцией.
  • Повторно отправленный целиком старый HTTP-запрос — 409 nonce_reused. Nonce одноразовый; обновите подпись.
  • После 504 сначала выполните GET /payments/{payment_id}, и только потом решайте о повторе.
← НазадПодпись HMACДальше →Каналы и возможности
Была ли страница полезной?