IOSOR

IOSOR Знания

Идемпотентност на send API: дубликати, повторения и пари

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

Timeout-ите се случват. Балансьорите правят retry. Мобилните клиенти правят double-tap. Без идемпотентност продуктът "изпрати веднъж" става двойно prepaid дебитиране и дублиран OTP UX. Това ръководство е за engineering и technical product, които интегрират white-label prepaid messaging API — където всеки дубликат се вижда в портфейла. IOSOR очаква money-aware интеграции: удостоверени извиквания, корелабилни дебити и клиентски грешки, които никога не изхвърлят чужди brand payload-и.

Защо дубликатите стават парични проблеми

Режим на отказ Потребителят вижда Портфейлът вижда
Client timeout + сляп retry Два OTP / два алерта Два дебита
Неидемпотентен webhook handler Двойни side effects Объркване при success
User resend върху auto-retry Раздразнени потребители Натрупани единици
Липсва корелация Тикети "не успя" Несъвпадащи ledger редове

Демотата прощават. Production finance — не. При prepaid интензитет уикенд със слепи retry става проект за равнение, не бележка под линия в логовете. Проектирайте happy path и timeout пътя със същото правило за дебит.

Ключове за идемпотентност, които оцеляват при retry

Сериозен send път приема ключ, генериран от клиента (или еквивалент), който е уникален за бизнес намерение, а не за TCP опит. Трябва да връща същия accepted резултат при replay в ясно TTL прозорче. Това предотвратява тихото създаване на втори дебит за същото намерение. Ключът трябва да се логва до message ID и prepaid референция. Трябва да работи през timeout-и, gateway retry и support redrive.

Бюджети за retry срещу повторно изпращане от потребителя

Автоматичните retry се нуждаят от бюджет: макс опити, backoff и кои класове грешки са retryable. Повторното изпращане от потребителя е различна продуктова акция със собствени лимити и prepaid разход. Смесването им превръща нестабилната мрежа във финансово събитие. Комбинирайте двете със stop-on-low-balance и ясни причини за отхвърляне, за да споделят product и finance една истина.

Чеклист на купувач / engineering

  1. Документирана семантика на ключа за идемпотентност и TTL.
  2. Replay тест, който доказва един дебит за едно намерение.
  3. Отделяне на бюджета за auto-retry от логиката за user resend.
  4. Корелационни ID-та между request, статус на съобщението и prepaid ledger.
  5. Staging, който упражнява реални коридори — mock зелените светлини не са лансирания.
  6. Хигиена на ключовете и least privilege за send credentials.
  7. Обработка на 429 и 503 кодове без загуба на оригиналния intent ключ.
  8. Автоматизирани аларми за високи нива на отхвърляне на дублирани ключове.

Червени флагове

  • "Просто retry до 200" без използване на ключове за идемпотентност.
  • Webhook handler-и, които не са идемпотентни и задействат side effects два пъти.
  • Пълни secret ключове или auth токени в логове или тикети за поддръжка.
  • Грешки, които поставят upstream brand payload-и или вътрешни stack trace-ове към крайните потребители.
  • Липса на лимити за retry.

Започнете с IOSOR

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

Обобщение IOSOR

Правете: третирайте всяко изпращане първо като събитие в ledger. Ключът е уникален за бизнес намерение, не за TCP опит.

Полезно ли беше ръководството?

Свързани ръководства