送信 API の冪等性：重複・リトライ・お金

タイムアウトは起きる。ロードバランサはリトライする。モバイルはダブルタップする。冪等性がなければ、「一度送る」製品はプリペイド二重課金と OTP 重複 UX になる。本ガイドはホワイトラベルのプリペイド・メッセージング API を統合するエンジニアリングとテクニカルプロダクト向け——重複はすべてウォレットに見える。

IOSOR はお金を意識した統合を求める：認証済み呼び出し、突き合わせ可能なデビット、外部ブランドの生ペイロードを出さないクライアントエラー。月間プラットフォーム利用がおおよそ USD 1,000+ に近づくと、重複規律は必須になる。送信をまず台帳イベント、次にネットワーク呼び出しとして扱い、財務とオンコールが一つの物語を共有できるようにする。

なぜ重複がお金の問題になるのか

デモは許す。本番財務は許さない。プリペイド強度では、週末の盲目リトライはログの脚注ではなく突合プロジェクトになる。ハッピーパスとタイムアウトパスは同じデビット規則で設計する。

リトライに耐える冪等キー

本格的な送信パスはクライアント生成キー（または同等物）を受け付け、次を満たす：

1. ビジネス意図ごとに一意（TCP 試行ごとではない）
2. 明確な TTL 内のリプレイで同じ受理結果を返す
3. 同じ意図に対し黙って二度目のデビットを作らない
4. メッセージ ID とプリペイド参照の横に記録される
5. タイムアウト、ゲートウェイリトライ、サポート再配送で機能する

唯一の助言が「タイムアウトを伸ばせ」なら、冪等性の物語はない。キーはランタイムとワーカーをまたいで安定し、二番目のプロセスが同じクリック用に新しいキーを発明できないようにする。

リトライ予算とユーザー再送

自動リトライには予算が要る：最大回数、バックオフ、再試行可能なエラー種別。ユーザー起点の再送は別のプロダクト行動で、独自のレート制限とプリペイド費用がある。混ぜると不安定なネットワークが週末のウォレット事件になる。

両方を低残高停止と明確な拒否理由に結びつけ、プロダクトと財務が一つの真実を共有する。安全にリトライできる HTTP ステータスとプラットフォームコードを公開し、それ以外は人間または新しいビジネス意図が必要なハードストップとする。

バイヤー / エンジニアリング チェックリスト

1. 冪等キーの意味と TTL を文書化。
2. 1意図1デビットを証明するリプレイテスト。
3. 自動リトライ予算とユーザー再送を分離。
4. リクエスト・メッセージ状態・プリペイド台帳を結ぶ相関 ID。
5. 実廊下でのステージング——Mock の緑はローンチではない。
6. 送信クレデンシャルのキー衛生と最小権限。

危険信号

• キーなしで「200 までリトライ」
• 冪等でない webhook ハンドラ
• ログやチケットに完全な秘密鍵
• 上流ブランドの生ペイロードをエンドユーザーに貼るエラー
• 重複を防いだと財務に証明できない

営業デッキやランブック貼り付けにこれらがあれば、証拠でギャップを埋めるまで統合を止める。

IOSOR で始める

送信コンソールで、クライアント生成の冪等キー付き OTP または警報を一つ出す。クライアントタイムアウトを強制し、キー TTL 内で同一リクエストを再送する。prepaid ledger を開く。その意図は借方一つとユーザーが見るメッセージ一つだけ。二行ならキーがリトライを生き延びていない。Live のままにする前に TTL とハンドラを直せ。

• ローンチを生き抜くWebhook習慣
• パイロットから本番へのAPIレート制限
• 送信前のNANPオーバーレイ：財務向けデータ品質管理

IOSORの要点

やる：送信は先に ledger 事象として扱う。冪等キーは業務意図ごとに一意であり、TCP 試行ごとではない。自動リトライには予算がある。ユーザーの再送タップは別の製品動作で、独自の prepaid コストを持つ。

やるな：キーなしで 200 まで叩くこと。非冪等 webhook に二度目の副作用を許すこと。一タップで OTP 二つは金の欠陥であり、ネットワークの話ではない。