Идемпотентность Slots API, повторы, неизвестные состояния и сверка

Краткий ответ

Идемпотентность, повторы и сверка — не три независимые функции. Они образуют единую цепочку обработки сбоев: стабильные идентификаторы распознают одно и то же бизнес-намерение; семантика идемпотентности определяет, безопасно ли повторение; ограниченные повторы обрабатывают временные сбои; сверка сопоставляет запросы с итоговым финансовым результатом; а ручная эскалация обрабатывает состояния, которые автоматизация все еще не может безопасно разрешить.

Самое опасное предположение: «тайм-аут означает сбой, значит, отправим еще раз». Сервер может завершить запрос, даже если его ответ потерян при передаче. Тогда у вызывающей стороны неизвестное состояние, а не подтвержденный сбой. Без явной идемпотентности или семантики поиска автоматический повтор может создать дублирующую сессию, перевод или запись в реестре.

Пять понятий, которые нужно разделять

Понятие	Рабочее определение	Чего оно само по себе не гарантирует
Стабильный идентификатор	Долговечное значение, сопоставляющее один и тот же запрос, транзакцию, раунд или ставку	Наличие ID не доказывает дедупликацию на стороне сервера
Идемпотентность	Ожидается, что повторение одного и того же бизнес-намерения даст тот же итоговый эффект, что и однократная обработка	Ответы не обязаны быть текстуально идентичны, и запрос все еще может завершиться ошибкой
Повтор	Еще одна попытка в заданных условиях, с ограничением числа попыток и временным бюджетом	Постоянная ошибка не станет успешной, а повтор не заменяет поиск состояния
Сверка	Сопоставление намерения запроса, бизнес-результата, записей транзакции или раунда и эффекта в реестре	Она не принимает автоматически каждое компенсационное решение
Ручная эскалация	Уполномоченный сотрудник расследует и принимает решение, когда автоматизация не может безопасно сделать вывод	Человеческое суждение не восполняет отсутствующие журналы или определения протокола

HTTP-методы не определяют бизнес-семантику проекта. RFC 9110 определяет PUT, DELETE и безопасные методы как идемпотентные и предостерегает клиентов от автоматического повтора неидемпотентных запросов, если их фактическая семантика не известна как идемпотентная или клиент не может установить, что исходный запрос не был применен. Вызовы платформы, показанные в публичной справке API, используют POST, поэтому безопасное поведение при повторе нельзя выводить только из HTTP-метода.

1. Стабильные идентификаторы: отделяйте трассировку от бизнес-идентичности

Надежному решению обычно нужны как минимум два класса идентификаторов:

ID трассировки запроса: сопоставляет одну транспортную попытку с журналами, ответом и диагностическими материалами.
ID бизнес-транзакции: идентифицирует одно бизнес-намерение и сопоставляет переводы, движения в реестре, раунды или ставки.

Публичная справка API показывает reqTraceId и в некоторых потоках транзакций поля merchantTransactionId, transactionId, roundId и betId. В ней merchantTransactionId описан как уникальный идентификатор транзакции мерчанта, который может поддерживать сверку.

Эти поля дают подсказки для прослеживаемости. Они не устанавливают неподтвержденное поведение: дедуплицируется ли каждая операция, каковы область и срок хранения дедупликации, что происходит при поступлении одного ID с разными параметрами или возвращает ли повтор исходный результат. Эта семантика требует формального протокола и тестов в применимой среде.

Проект IETF draft-ietf-httpapi-idempotency-key-header-07 предлагал заголовок Idempotency-Key. По состоянию на 9 августа 2026 года эта версия была просрочена и архивирована и не стала RFC. Ее можно рассматривать лишь как исторический входной материал для проектирования, а не как действующий стандарт, протокол AG или доказательство поддержки AG этого заголовка.

2. Повторы: делайте ограниченные попытки только для безопасных операций и сбоев

Автоматический повтор должен удовлетворять обоим условиям: сбой классифицирован как временный, а повторение безопасно в рамках применимого протокола.

Сценарий	Принцип по умолчанию	Условие перед автоматическим повтором
Запрос только на чтение или список	Можно рассмотреть ограниченный повтор	Протокол подтверждает отсутствие побочного эффекта, а сбой является временным
Создание сессии	Не создавайте повторно только из-за тайм-аута	Явная идемпотентность или поиск существующей сессии по ее исходному идентификатору
Изменение кошелька или перевода	По умолчанию сначала проверьте состояние или выполните сверку	Подтверждены бизнес-ID, область идемпотентности и поведение при дубликате
Обработка callback	Потребитель должен обнаруживать повторные события	Обе стороны согласовали стабильный ID события или транзакции для дедупликации
Ошибка параметра, разрешения или подписи	Не повторяйте тот же запрос автоматически	Исправьте параметр, доступ, часы или учетные данные и примите новое решение
Тайм-аут или разрыв соединения	Пометьте результат как неизвестный	Сначала выполните запрос по исходному ID; повторяйте только при установленной безопасной семантике

Повторам нужны тайм-аут на каждую попытку, максимальное число попыток, общий временной бюджет и условия остановки. Эта статья не предписывает числовые значения: они зависят от семантики API, ограничений вышестоящих систем, бизнес-риска и соглашения сторон.

3. Экспоненциальная задержка и джиттер: избегайте синхронизированной нагрузки

Когда временный сбой безопасно повторять, ограниченная экспоненциальная задержка со случайным джиттером может распределить попытки во времени. Концептуально задержка увеличивается с каждой попыткой до максимума, а джиттер не дает множеству клиентов повторять запрос в один и тот же момент.

И AWS, и Google документируют ценность задержки и джиттера. Google также ясно указывает, что допустимость повтора зависит от того, допускает ли сбой повтор и является ли операция идемпотентной. Алгоритм задержки не может сделать безопасной неидемпотентную запись и не заменяет общий бюджет повторов.

Избегайте следующих антипаттернов:

немедленных или неограниченных циклов повторов;
единой политики повторов для каждой HTTP- и бизнес-ошибки;
повторов на уровнях шлюза, SDK, сервиса и очереди, которые умножают друг друга;
генерации нового ID бизнес-транзакции для каждой попытки, что мешает распознать исходное намерение;
журналирования ключей, полных учетных данных или ненужных чувствительных данных при повторах;
бесконечного продолжения автоматических повторов после повторяющихся сбоев.

RFC 9110 также требует осторожности с автоматическими повторами: повторный сбой не должен превращаться в неограниченное воспроизведение.

4. Неизвестное состояние: не называйте неопределенность сбоем

Когда запрос покинул вызывающую сторону, но полный бизнес-результат не вернулся, используйте отдельное состояние UNKNOWN. Нейтральный к протоколу поток можно представить так:

NEW -> SENT -> CONFIRMED_SUCCESS
            -> CONFIRMED_FAILURE
            -> UNKNOWN -> QUERY_OR_RECONCILE -> CONFIRMED_SUCCESS
                                           -> CONFIRMED_FAILURE
                                           -> MANUAL_REVIEW

В состоянии UNKNOWN запрашивайте существующие результаты, записи транзакций или движения в реестре по исходному запросу или ID бизнес-транзакции. Если в протоколе нет авторитетного пути поиска, остановите автоматические действия, которые могут продублировать эффект, сохраните контекст и эскалируйте. Не предполагайте сбой.

Метки состояний, API поиска и терминальные состояния должны следовать протоколу сторон. Эта диаграмма — метод проектирования; она не утверждает, что AG реализует именно эти состояния.

5. Сверка: используйте несколько записей, чтобы установить окончательный эффект

Сверка — это не просто сравнение двух значений баланса. Для потоков кошелька, ставки или выигрыша сопоставляйте как минимум:

исходное бизнес-намерение и ID трассировки запроса;
ID бизнес-транзакции мерчанта или платформы;
идентификаторы транзакции, раунда и ставки контрагента;
сумму, валюту, направление и интерпретацию времени;
бизнес-результат API и последующие записи;
движение в реестре, текущий баланс и окончательное состояние обработки.

Полезные результаты включают сверено, подтвержденный сбой, дубликат, несоответствие суммы или валюты, отсутствующую запись и неизвестное состояние. Для каждого расхождения нужны заранее определенные владелец, набор доказательств, полномочие на компенсацию и условие закрытия. Не отправляйте исходное финансовое изменение повторно вместо сверки.

Частота, хранение и допуски зависят от бизнес-риска, объема, модели кошелька и договора. Эта статья не устанавливает фиксированные периоды или пороги AG.

6. Когда ручная эскалация обязательна

Остановите автоматизацию и откройте аудируемую ручную проверку, если применимо хотя бы одно из следующего:

ограниченный бюджет повторов исчерпан, а бизнес-состояние остается неизвестным;
один бизнес-ID фигурирует с разными суммами, валютами, счетами или другими критически важными параметрами;
результат запроса, запись транзакции и движение в реестре противоречат друг другу;
авторитетная запись, определенная протоколом, не найдена или критически важные журналы неполны;
предполагаются двойное списание, двойная выплата, несанкционированный доступ или инцидент безопасности;
автоматическая компенсация может увеличить финансовое, комплаенс- или клиентское воздействие.

Запись должна включать исходные ID, временную шкалу, уже выполненные действия, доказательства, оценку риска, утверждающее лицо и итоговый результат закрытия. Секреты и учетные данные не должны попадать в текст тикетов.

Одностраничный контрольный список реализации

Определите стабильные ID отдельно для трассировки запросов и бизнес-транзакций.
Укажите область идемпотентности, поведение при конфликте и семантику ответа на повтор для каждой операции с побочными эффектами.
Разделите временные ошибки, постоянные ошибки и неизвестные состояния.
Повторяйте автоматически только тогда, когда безопасность повторения подтверждена.
Установите тайм-ауты, общий бюджет, ограниченный максимум экспоненциальной задержки и джиттер для допустимых путей.
Не допускайте неожиданного умножения повторов на нескольких системных уровнях.
Предоставьте поиск или сверку по исходному ID для неизвестных состояний.
Сверяйте доказательства по транзакции, раунду, сумме, валюте и реестру.
Определите условия остановки автоматизации и владельца ручной эскалации.
Тестируйте в staging случаи тайм-аута, потерянного ответа, дублирующей отправки и расхождения записей.

Что в настоящее время можно оценить на этом сайте

Публичная справка API показывает идентификаторы запросов и некоторых бизнес-транзакций, раундов и ставок.
В примечаниях к интерфейсу требуется оценивать бизнес-результат в теле ответа, а не только HTTP-статус.
Запросы к кошельку, транзакциям, раундам и ставкам могут информировать проектирование тестов прослеживаемости и сверки.
Текущие страницы описывают единый и переводной кошельки, но проект надежности должен следовать выбранной модели кошелька и формальному протоколу.

Границы, о которых следует помнить

Эта страница не утверждает, что все эндпоинты AG POST идемпотентны или что AG поддерживает заголовок Idempotency-Key.
Она не выдумывает для AG область дедупликации, хранение, ответы на конфликты, число повторов, параметры задержки или графики сверки.
Она не добавляет эндпоинтов запросов, компенсации, состояний или production.
Она не обещает нулевых дубликатов, нулевых потерь, абсолютной согласованности, абсолютной безопасности, фиксированной производительности или SLA.
Публичные примеры API не являются производственным протоколом, гарантией времени выполнения или записью о допуске проекта в production.

Часто задаваемые вопросы

Можно ли автоматически повторить неудачный POST-запрос?

Не только на основании «неудачи» или POST. Сначала установите, является ли сбой временным, мог ли исходный запрос уже дать эффект и предоставляет ли формальный протокол идемпотентность или поиск по исходному ID. В противном случае операция относится к обработке неизвестного состояния и сверке.

Означает ли тайм-аут, что транзакция не удалась?

Нет. Тайм-аут означает лишь, что вызывающая сторона не получила полный результат вовремя. Сервер мог не начать обработку, все еще обрабатывать запрос либо завершить его успешно или с ошибкой. Выполните запрос или сверку, используя исходный бизнес-ID.

Доказывает ли уникальный ID транзакции идемпотентность?

Нет. Это важная основа для распознавания одного бизнес-намерения, но протокол также должен определять, как сервис хранит и сопоставляет ID, его область и срок действия, конфликты параметров и результат, возвращаемый при повторе.

Должен ли повтор получать новый ID запроса?

Это зависит от того, как протокол отделяет одно бизнес-намерение от транспортной попытки. ID бизнес-транзакции обычно должен оставаться стабильным. Будет ли ID трассировки повторно использоваться или производиться от исходного, должно быть явно зафиксировано в контракте интерфейса, а не выведено из этой статьи или названия поля.

Связанные материалы и следующие шаги

Основные страницы: публичная справка API, Slots API и процесс интеграции
Существующее руководство: единый кошелек и переводной кошелек
Продолжите с контрольным списком приемки от staging до production и глоссарием Slots API

Чтобы спроектировать надежность для конкретной интеграции, используйте раздел «Связаться с нами» и укажите модель кошелька, направление вызова, критически важные бизнес-операции и текущие возможности сверки. Затем AG сможет подтвердить идентификаторы, семантику поиска, границы повторов и владельца эскалации по формальному протоколу, не обещая заранее поведение в production.

Источники и область применения

Соответствующие поля и область страниц приведены в публичной справке API, обзоре Slots API и процессе интеграции. Реализация по-прежнему должна следовать протоколу и наблюдаемому поведению среды, согласованным обеими сторонами.

Общие источники по надежности:

IETF RFC 9110: HTTP Semantics — для идемпотентных методов и границ автоматических повторов.
IETF Datatracker: The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-07 — просрочен и архивирован по состоянию на 9 августа 2026 года и не является RFC; только исторический входной материал для проектирования.
AWS Builders’ Library: Making retries safe with idempotent APIs и Timeouts, retries and backoff with jitter.
Google Cloud: Retry strategy — для общих принципов повторяемых сбоев, идемпотентности, экспоненциальной задержки и джиттера.

Эти источники объясняют общие паттерны. Они не подтверждают, что AG использует алгоритм, параметры или заголовок какого-либо поставщика. Владельцы API, кошелька, SRE, безопасности и сверки должны проверить семантику проекта и примеры полей.

Нужно превратить это руководство в план проекта?

Материал помогает оценить проект, но не заменяет техническое, договорное, сертификационное или правовое подтверждение.

Связаться с нами