支払いエラーの分類法 (Payment Failure Taxonomy)

前のセクションでは、PaymentFailed などのセマンティック イベントによってプロバイダーのステータス コードが隠蔽されることがわかりました。しかし、単一の PaymentFailed イベントでも十分ではありません。なぜなら、「失敗」という言葉はまったく異なる現実をカバーしているからです。

カードの拒否、ネットワーク タイムアウト、429 を返す PSP、および 500 を返す PSP はすべて「失敗」として表示される可能性があります。しかし、それぞれがまったく異なるアクションを必要とします。この章では、これらの違いを可視化する分類法の構築について説明します。```text PaymentFailed ├─ Business Decline (kart reddedildi — retry etme) ├─ Timeout (belirsiz sonuç — dikkatli retry) ├─ Rate Limited (429) (çok istek — backoff ile retry) └─ Infrastructure (5xx) (provider tarafı arıza — retry)

## 最初に説明した概念```text
📦 Business Decline
PSP'nin, kartın kendisiyle ilgili bir nedenle isteği reddetmesi: yetersiz bakiye, dolandırıcılık şüphesi.

📦 Transient Hata
Aynı isteğin tekrar denenmesi mantıklı olan, geçici bir arıza: timeout, 5xx, 429.

📦 Permanent Hata
Tekrar denemenin sonucu değiştirmeyeceği hata: geçersiz kart numarası, desteklenmeyen para birimi.

📦 Belirsiz Sonuç
İsteğin PSP'ye ulaşıp ulaşmadığının bilinmediği durum: bağlantı timeout'u.
```事業の衰退を再試行するのは時間の無駄です。不確実な結果を踏まえて再試行しないと、支払いが滞るという大きなリスクが生じます。これら 2 つのリスクを区別するために分類が存在します。

## 4 つの基本カテゴリ

**ビジネスの衰退**: PSP はリクエストを受け取り、処理し、決定を下しました。カードは拒否されました。これはシステムエラーではなく、ビジネス上の決定です。再試行しても結果は変わりません。ユーザーに別の支払い方法を提案する必要があります。

**タイムアウト / 不確定な結果**: リクエストは送信されましたが、応答は届きませんでした。ここで危険なのは、支払いは PSP 側で行われた可能性があり、応答が失われるだけであるということです。このカテゴリは、やみくもに「再試行」するだけでは対処できません。まず、(冪等性キーを使用して) 状況を調べてから、決定を下す必要があります。

**レート制限 (429)**: PSP はリクエスト量の制御を一時的に拒否しています。これはエラーではなく、信号です。すぐに再試行すると状況がさらに悪化します。バックオフで待つ必要があります。

**インフラストラクチャ (5xx)**: PSP 側に障害があります。リクエストが処理されていない場合、通常は再試行しても安全ですが、5xx が常に受信される場合、これはサーキット ブレーカー信号です。```text
Hata alındı
  │
  ├─ PSP isteği net biçimde reddetti mi? → Business Decline → retry etme
  │
  ├─ Yanıt hiç gelmedi mi? → Belirsiz Sonuç → önce durumu sorgula
  │
  ├─ 429 mu? → Rate Limited → backoff ile retry
  │
  └─ 5xx mi? → Infrastructure → retry, ama circuit breaker'ı izle
```## 単一の「再試行」ルールでは不十分な理由

すべてのエラーを同じ再試行ロジックで処理するワーカーは、2 つの方法で失敗します。1 つは、ビジネスの失敗を無意味に再試行する (ユーザー エクスペリエンスを遅らせ、場合によってはカード ネットワークの制限を押し上げる) か、またはまったく再試行せずに曖昧な結果を残す (実際に成功した支払いをシステムが忘れる原因となる) ことです。この分類法では、各エラーを正しいボックスに入れることで、これらのリスクの両方を軽減します。

## コードで分類をどのように表現するか

セマンティック イベントの `failureReason` フィールドには、プロバイダーの生のエラー テキストではなく、これら 4 つのカテゴリのいずれかが含まれている必要があります。プロバイダー ゲートウェイは、生のエラーをこのカテゴリにマッピングする責任があります。これは、前のセクションの変換層の拡張です。

|失敗の理由 |再試行は適切ですか?アクション |
| --- | --- | --- |
|ビジネスの衰退 |いいえ |ユーザーに別の方法を提案する |
|あいまいなタイムアウト |最初に問い合わせる |状況照会と決定 |
|レートリミテッド |はい |バックオフで再試行 |
|インフラストラクチャエラー |はい |ウォッチリトライ + サーキットブレーカー |

## 混同されやすい区別```text
❌ Her hata retry edilmelidir
✓ Business decline retry edilmemelidir; sonuç değişmez

❌ Timeout = hata yok, sadece tekrar dene
✓ Timeout = belirsizlik; önce gerçek durum sorgulanmalı

❌ 429 bir arızadır
✓ 429 bir sinyaldir; sistem sizi kasıtlı olarak yavaşlatıyor
```## カテゴリ間の簡単な比較

|カテゴリー |結果は明らかですか？再試行は意味がありますか |典型的な原因 |
| --- | --- | --- | --- |
|ビジネスの衰退 |はい |いいえ |カード、残高、詐欺 |
|タイムアウト |いいえ |最初に問い合わせる |ネットワーク、PSP の遅さ |
|レート制限 |はい |はい (待機中) |ボリュームコントロール |
|インフラ |はい |はい | PSP側の故障｜

## 分類を設定する際のチェックリスト

1. プロバイダーから返された各エラー コードは、4 つのカテゴリのいずれかに明確に対応していますか?
2. 新しいマップされていないエラー コードが到着すると、システムはデフォルトでステータスを照会しますか、それとも盲目的に再試行しますか? (本当のデフォルト: クエリステータス。)
3. タイムアウト シナリオでは、再試行前のステータス チェックが実際に実装されていますか?
4. 429 のバックオフ時間には、PSP の `Retry-After` ヘッダー (存在する場合) が考慮されますか?
5. 5xx 周波数はサーキットブレーカーをトリガーする指標として監視されていますか?
6. ビジネスが衰退した後のユーザー フローは、再試行サイクルに入ることはありませんか?

## この記事で覚えておくべきこと

1. 「失敗」は単一の状態ではありません。それらは 4 つの異なる現実であり、少なくとも 4 つの異なるアクションが必要です。
2. 事業の衰退は再試行されません。タイムアウトは盲目的に再試行されるのではなく、最初にクエリされます。
3. 429 は信号、5xx は障害です。どちらも再試行されますが、規律が異なります。
4. この分類法により、生のプロバイダー テキストからではなく、独自の `failureReason` 列挙型からエラーを読み取ることができるようになります。

> エラーを理解せずに再試行ポリシーが作成された場合。それは役に立たないだけでなく、静かに害を及ぼします。

次のセクションでは、バックオフ、ジッター、キャップ、サーキット ブレーカーの 4 つのカテゴリごとに実際の再試行アルゴリズムを設定します。