Taxonomie des erreurs de paiement (Taxonomie Des Erreurs DE Paiement)

Dans la section précédente, nous avons vu que les événements sémantiques tels que PaymentFailed masquent les codes de statut du fournisseur. Mais même un seul événement PaymentFailed ne suffit pas ; car le mot « échec » recouvre des réalités très différentes.

Un rejet de carte, un timeout réseau, une PSP renvoyant 429 et une PSP renvoyant 500 peuvent tous apparaître comme un « échec » ; mais chacun nécessite une action complètement différente. Ce chapitre aborde la construction d’une taxonomie qui rend ces différences visibles.```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)

## Concepts à la première mention```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.
```Réessayer un déclin d’entreprise est une perte de temps ; Ne pas réessayer avec un résultat incertain constitue un risque réel de défaut de paiement. La taxonomie existe pour distinguer ces deux risques.

## Quatre catégories de base

**Déclin de l'activité** : PSP a reçu la demande, l'a traitée et a pris sa décision : la carte a été rejetée. Ce n’est pas une erreur système, c’est une décision commerciale. Réessayer ne change pas le résultat ; Il est nécessaire de proposer un autre moyen de paiement à l'utilisateur.

**Timeout / résultat indéterminé** : la demande a été envoyée mais la réponse n'est jamais arrivée. Le danger ici est que le paiement a peut-être eu lieu du côté PSP, seule la réponse est perdue pour vous. Cette catégorie ne peut pas être abordée par un « réessai » aveugle ; Il faut d’abord remettre en question la situation (avec la clé de l’idempotence), puis prendre une décision.

**Taux limité (429)** : la PSP vous refuse temporairement le contrôle du volume des demandes. Ce n'est pas une erreur, c'est un signal. Réessayer immédiatement ne fera qu'empirer la situation ; Il faut attendre avec recul.

**Infrastructure (5xx)** : Il y a une panne du côté de la PSP. Si la demande n'a pas été traitée, il est généralement prudent de réessayer, mais si un 5xx est constamment reçu, il s'agit d'un signal de disjoncteur.```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
```## Pourquoi une seule règle de « réessayer » ne suffit pas

Un travailleur qui traite toutes les erreurs avec la même logique de nouvelle tentative échouera de deux manières : il réessayera inutilement des refus d'affaires (retardant l'expérience utilisateur, repoussant parfois les limites du réseau de cartes), ou il laissera des résultats ambigus sans réessayer du tout (ce qui fera oublier au système un paiement qui a réellement réussi). La taxonomie réduit ces deux risques en plaçant chaque erreur dans la bonne case.

## Comment représentons-nous la taxonomie dans le code

Le champ `failureReason` de l'événement sémantique doit contenir l'une de ces quatre catégories, et non le texte d'erreur brut du fournisseur. La passerelle du fournisseur est chargée de mapper l'erreur brute à cette catégorie — il s'agit d'une extension de la couche de traduction de la section précédente.

| Raison de l'échec | Une nouvelle tentative est-elle appropriée ? Actions |
| --- | --- | --- |
| Déclin des affaires | Non | Proposer une autre méthode à l'utilisateur |
| AmbiguousTimeout | Requête d'abord | Enquête sur le statut puis décision |
| Tarif Limité | Oui | réessayez avec interruption |
| Erreur d'infrastructure | Oui | Regarder Réessayer + Disjoncteur |

## Distinctions souvent confuses```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
```## Comparaison rapide entre les catégories

| Catégorie | Le résultat est-il clair ? Est-il logique de réessayer | Cause typique |
| --- | --- | --- | --- |
| Déclin des affaires | Oui | Non | Carte, solde, fraude |
| Délai d'attente | Non | Requête d'abord | Réseau, lenteur PSP |
| Tarif Limité | Oui | Oui (en attente) | Contrôle du volume |
| Infrastructures | Oui | Oui | Dysfonctionnement côté PSP |

## Liste de contrôle lors de la mise en place d'une taxonomie

1. Chaque code d'erreur renvoyé par le fournisseur correspond-il clairement à l'une des quatre catégories ?
2. Lorsqu'un nouveau code d'erreur non mappé arrive, le système interroge-t-il l'état par défaut ou réessaye-t-il aveuglément ? (Vrai par défaut : état de la requête.)
3. Dans le scénario d'expiration, la vérification de l'état avant nouvelle tentative est-elle réellement mise en œuvre ?
4. Le délai d'attente pour 429 prend-il en compte l'en-tête `Retry-After` de la PSP (le cas échéant) ?
5. La fréquence 5xx est-elle surveillée comme mesure susceptible de déclencher un disjoncteur ?
6. Le flux d’utilisateurs après un déclin de l’activité n’entre-t-il jamais dans le cycle de nouvelle tentative ?

## Ce qu'il faut retenir de cet article

1. « L’échec » n’est pas un seul état ; Ce sont quatre réalités différentes qui nécessitent au moins quatre actions différentes.
2. Le déclin des affaires n’est pas retenté ; le délai d'attente n'est pas réessayé aveuglément, il est d'abord interrogé.
3. 429 est un signal, 5xx est un défaut ; Les deux sont retentés mais avec une discipline différente.
4. La taxonomie rend l'erreur lisible à partir de votre propre énumération `failureReason`, et non à partir du texte brut du fournisseur.

> Si une politique de nouvelle tentative a été écrite sans comprendre l'erreur ; Non seulement c’est inutile, mais cela cause silencieusement du mal.

Dans la section suivante, nous configurerons l'algorithme de nouvelle tentative pour chacune de ces quatre catégories : interruption, gigue, plafond et disjoncteur.