IOSOR

IOSOR Знање

Идемпотентност send API-ја: дупликати, retry и новац

Водич за програмере prepaid send API — кључеви идемпотентности, безбедни retry, заштита од дупликата и корелација погодна за ledger, да грешке инжењеринга не постану финансијски инциденти.

Timeout-и се дешавају. Балансери раде retry. Мобилни клијенти раде double-tap. Без идемпотентности производ "пошаљи једном" постаје двоструко prepaid терећење и дупли OTP UX. Овај водич је за engineering и технички product који интегришу white-label prepaid messaging API — где је сваки дупликат видљив у новчанику.

IOSOR очекује money-aware интеграције: аутентификоване позиве, корелабилна терећења и клијентске грешке које никад не избацују туђе brand payload-е. Близу USD 1.000+ месечне употребе платформе дисциплина дупликата више није опционална.

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

Режим отказа Корисник види Новчаник види
Client timeout + слепи retry Два OTP / два алерта Два терећења
Неидемпотентан webhook handler Двоструки side effect-и Збуњеност код success-а
User resend на auto-retry Изнервирани корисници Нагомилане јединице
Недостаје корелација Тикети "није успело" Неусклађени ledger редови

Демои праштају. Production finance не. При prepaid интензитету викенд слепих retry постаје пројекат усаглашавања, не фуснота у логовима. Дизајнирајте happy path и timeout пут истим правилом терећења.

Кључеви идемпотентности који преживљавају retry

Озбиљан send пут прихвата клијентски генерисан кључ који је јединствен по пословној намери, не по TCP покушају. Мора вратити исти accepted резултат при replay у јасном TTL прозору. Ово спречава тихо стварање другог терећења за исту намеру. Кључ логирајте поред message ID и prepaid референце.

Буџети retry насупрот корисничком поновном слању

Аутоматски retry захтевају буџет: макс покушаја, backoff и дефиницију retryable грешака. User-initiated resend је друга продуктна акција са сопственим лимитима и prepaid трошком. Мешање ова два света претвара нестабилну мрежу у викенд финансијски инцидент. Упарите обоје са stop-on-low-balance и јасним разлозима одбијања.

Чеклиста купца / инжењеринга

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

Црвене заставе

  • "Retry-уј до 200" без коришћења кључева идемпотентности.
  • Webhook handler-и који нису идемпотентни и окидају side effect-е двапут.
  • Пуни secret кључеви или auth токени у логовима или support тикетима.
  • Грешке које враћају upstream brand payload-е или stack trace крајњем кориснику.
  • Недостатак мониторинга дуплих кључева.

Почните са IOSOR

У конзоли слања испалите један OTP или узбуну са клијентским кључем идемпотенције. Присилите тајмаут клијента и поновите исти захтев унутар TTL кључа. Отворите prepaid ledger: та намера мора показати један дебит и једну видљиву поруку. Два реда значе да кључ није преживео поновни покушај — поправите TTL и обрађивач пре него што коридор остане Live.

Резиме IOSOR

Радите: сваки слање прво третирајте као догађај леџера. Кључ је јединствен по пословној намери, не по TCP покушају. Ауто-поновни покушај има буџет; тап корисника за поновно слање је друга производна радња са сопственим prepaid трошком.

Не радите: млатити до 200 без кључа нити дозволити неидемпотентном webhook-у други споредни ефекат. Два OTP за један тап је новчани баг, не мрежна прича.

Да ли је овај водич био корistan?

Повезани водичи