IOSOR

IOSOR База знаний

Идемпотентность send API: дубли, retry и деньги

Гайд для разработчиков prepaid send API — ключи идемпотентности, безопасные retry, защита от дублей и correlation, удобная ledger, чтобы ошибки инженерии не становились финансовым инцидентом.

Тайм-ауты случаются. Балансировщики делают повторные попытки. Мобильные клиенты нажимают кнопки дважды. Без идемпотентности продукт «отправить один раз» превращается в двойное списание с баланса и дублирование OTP. Этот гайд предназначен для инженеров и технических лидов, интегрирующих white-label API — где каждый дубль виден в кошельке. IOSOR ожидает интеграций, учитывающих движение средств: аутентифицированные вызовы, сопоставимые дебеты и ошибки клиента, которые никогда не выдают данные сторонних брендов.

Почему дубли становятся денежной проблемой

Режим отказа Что видит пользователь Что видит кошелек
Тайм-аут + слепой ретрай Два OTP / два алерта Два списания
Неидемпотентный webhook Двойные побочные эффекты Путаница в статусах
Ресенд поверх авто-ретрая Раздражение пользователя Умножение затрат
Отсутствие корреляции Тикеты «не сработало» Несводимые строки

Ключи идемпотентности, которые переживают retry

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

Бюджеты retry vs user resend

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

Чеклист buyer / engineering

  1. Документированная семантика ключей идемпотентности и их TTL.
  2. Тест на повтор, доказывающий одно списание на одну цель.
  3. Разделение бюджета авто-ретраев и логики ресенда пользователем.
  4. Correlation ID в запросах, статусах сообщений и реестре.
  5. Стейджинг на реальных коридорах — моки не заменяют запуск.
  6. Гигиена ключей и минимальные привилегии для учетных данных.
  7. Обработка кодов 429 и 503 без потери оригинального ключа.
  8. Автоалерты при высоком проценте отказов по duplicate-key.

Красные флаги

  • Совет «просто ретрай до победного 200» без использования ключей.
  • Обработчики вебхуков, которые не идемпотентны и запускают действия дважды.
  • Полные секретные ключи или токены в логах или тикетах поддержки.
  • Ошибки, выводящие внутренние трейсы или данные апстрим-брендов пользователю.
  • Отсутствие возможности доказать финансам, что дубль был предотвращен.
  • Использование только временных меток для обеспечения уникальности.

Старт с IOSOR

В консоли отправки выпустите один OTP или алерт с клиентским ключом идемпотентности. Сорвите клиентский таймаут и повторите тот же запрос внутри TTL ключа. Откройте prepaid-ledger: у этого намерения один debit и одно сообщение, которое видит пользователь. Две строки — ключ не пережил retry. Почините TTL и обработчик, пока коридор ещё не Live.

Итог IOSOR

Делайте: сначала событие ledger, потом сеть. Ключ уникален на бизнес-намерение, не на TCP-попытку. Автоповтор имеет бюджет; кнопка «отправить ещё» — другое действие со своей prepaid-ценой.

Не делайте: долбить до 200 без ключа и давать webhook без идемпотентности второй побочный эффект. Два OTP на одно нажатие — денежный баг, не сетевая легенда.

Был ли материал полезен?

Связанные гайды