IOSOR

IOSOR Wiedza

Idempotencja API wysyłki: duplikaty, retry i pieniądze

Przewodnik dla deweloperów prepaid send API — klucze idempotencji, bezpieczne retry, ochrona przed duplikatami i korelacja przyjazna ledgerowi, by błędy inżynierii nie stawały się incydentami finansowymi.

Timeouty się zdarzają. Balansery robią retry. Mobilni klienci robią double-tap. Bez idempotencji produkt "wyślij raz" staje się podwójnym obciążeniem prepaid i zdublowanym UX OTP. Ten przewodnik jest dla engineeringu i technical product, którzy integrują white-label prepaid messaging API — gdzie każdy duplikat widać w portfelu. IOSOR oczekuje integracji money-aware: uwierzytelnionych wywołań, korelowanych debetów i błędów klienta bez dumpowania obcych brand payloadów. Blisko USD 1 000+ miesięcznego użycia platformy dyscyplina duplikatów przestaje być opcjonalna. Traktuj każdy send najpierw jako zdarzenie ledger, potem jako wywołanie sieci — by finance i on-call dzieliły jedną narrację.

Dlaczego duplikaty stają się problemami pieniężnymi

Tryb awarii Użytkownik widzi Portfel widzi
Timeout klienta + ślepy retry Dwa OTP / dwa alerty Dwa debety
Nieidempotentny handler webhook Podwójne side effects Zamieszanie przy success
Resend użytkownika na auto-retry Zdenerwowani użytkownicy Narosłe jednostki
Brak korelacji Tickety "nie wyszło" Niezgodne wiersze ledger

Dema wybaczą. Finanse produkcji nie. Przy intensywności prepaid weekend ślepych retry staje się projektem rozliczeń, nie przypisem w logach. Zaprojektuj happy path i ścieżkę timeout z tą samą regułą debetu.

Klucze idempotencji, które przeżywają retry

Poważna ścieżka send przyjmuje klucz wygenerowany przez klienta, który jest unikalny na intencję biznesową, nie na próbę TCP. Przy replay w jasnym oknie TTL musi zwracać ten sam accepted result. To zapobiega cichemu tworzeniu drugiego debetu. Klucz loguj obok message ID i referencji prepaid. Musi działać przez timeouty, retry bramy i redrive supportu.

Budżety retry vs ponowne wysłanie użytkownika

Automatyczne retry potrzebują budżetu: max prób, backoff i klasy błędów retryowalne. Resend użytkownika to inny produkt z własnym limitem i kosztem. Mieszanie ich to przepis na weekendowy incydent finansowy. Paruj oba z blokadą przy niskim saldzie i jasnymi powodami odrzuceń.

Checklist kupującego / engineeringu

  1. Udokumentowana semantyka klucza i TTL.
  2. Test replay dowodzący jednego debetu na intencję.
  3. Oddzielenie budżetu auto-retry od logiki resend użytkownika.
  4. Correlation ID w requestach, statusach i ledgerze.
  5. Staging testujący realne korytarze, nie tylko mocki.
  6. Higiena kluczy i least privilege dla credentials.
  7. Obsługa 429 i 503 bez utraty klucza intencji.
  8. Automatyczne alerty dla wysokiego odrzutu duplikatów.

Czerwone flagi

  • Retry do skutku bez kluczy idempotencji.
  • Handlery webhook wyzwalające side effecty wielokrotnie.
  • Klucze w logach lub ticketach supportu.
  • Wycieki payloadów upstream do użytkownika końcowego.
  • Brak monitoringu rozbieżności między ledgerem a siecią.

Zacznij z IOSOR

W konsoli wysyłki odpalcie jeden OTP lub alert z kluczem idempotencji wygenerowanym przez klienta. Wymuście timeout klienta i powtórzcie to samo żądanie w TTL klucza. Otwórzcie prepaid-ledger: ta intencja musi pokazać jeden debit i jedną widoczną wiadomość. Dwa wiersze znaczą, że klucz nie przeżył retry — naprawcie TTL i handler, zanim korytarz zostanie Live.

Podsumowanie IOSOR

Róbcie: traktujcie każdy send najpierw jako zdarzenie ledger. Klucz jest unikalny na intencję biznesową, nie na próbę TCP. Autopowtórka ma budżet; tap użytkownika «wyślij znów» to inna akcja z własnym kosztem prepaid.

Nie róbcie: młotkować do 200 bez klucza ani pozwalać nieidempotentnemu webhookowi bić drugi efekt. Dwa OTP na jedno stuknięcie to bug pieniężny, nie opowieść o sieci.

Czy ten przewodnik był pomocny?

Powiązane przewodniki