Taxonomía de errores de pago (Taxonomia DE Errores DE Pago)

En la sección anterior, vimos que eventos semánticos como PaymentFailed ocultan los códigos de estado del proveedor. Pero ni siquiera un solo evento PaymentFailed es suficiente; porque la palabra "fracaso" abarca realidades muy diferentes.

Un rechazo de tarjeta, un tiempo de espera de la red, un PSP que devuelve 429 y un PSP que devuelve 500 pueden aparecer como "fallo"; pero cada uno requiere una acción completamente diferente. Este capítulo aborda la construcción de una taxonomía que haga visibles estas diferencias.```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)

## Conceptos en la primera mención```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.
```Reintentar un declive empresarial es una pérdida de tiempo; No volver a intentar el resultado incierto es un riesgo real de incumplimiento de pago. La taxonomía existe para distinguir entre estos dos riesgos.

## Cuatro categorías básicas

**Rechazo del negocio**: PSP recibió la solicitud, la procesó y tomó una decisión: la tarjeta fue rechazada. Esto no es un error del sistema, es una decisión empresarial. Intentarlo de nuevo no cambia el resultado; Es necesario sugerir otro método de pago al usuario.

**Tiempo de espera/resultado indeterminado**: La solicitud se envió pero la respuesta nunca llegó. El peligro aquí es que el pago puede haberse realizado por parte de la PSP, pero usted pierde la respuesta. Esta categoría no puede abordarse con un "inténtalo de nuevo" ciego; Primero se debe cuestionar la situación (con clave de idempotencia), luego se debe tomar una decisión.

**Tarifa limitada (429)**: PSP le niega temporalmente el control del volumen de solicitudes. Esto no es un error, es una señal. Intentarlo de nuevo inmediatamente empeorará la situación; Es necesario esperar con retroceso.

**Infraestructura (5xx)**: Hay una falla en el lado de la PSP. Si la solicitud no se ha procesado, normalmente es seguro volver a intentarlo, pero si se recibe un 5xx constantemente, se trata de una señal de disyuntor.```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
```## Por qué una sola regla de 'reintento' no es suficiente

Un trabajador que trata todos los errores con la misma lógica de reintento fallará de dos maneras: reintentará inútilmente rechazos comerciales (retrasando la experiencia del usuario, a veces superando los límites de la red de la tarjeta), o dejará resultados ambiguos sin volver a intentarlo (haciendo que el sistema olvide un pago que realmente fue exitoso). La taxonomía reduce ambos riesgos al colocar cada error en la casilla correcta.

## ¿Cómo representamos la taxonomía en el código?

El campo `failureReason` del evento semántico debe contener una de estas cuatro categorías, no el texto de error sin formato del proveedor. La puerta de enlace del proveedor es responsable de asignar el error sin procesar a esta categoría; esta es una extensión de la capa de traducción de la sección anterior.

| fracasoRazón | ¿Es apropiado volver a intentarlo? Acción |
| --- | --- | --- |
| Declive empresarial | No | Sugerir otro método al usuario |
| Tiempo de espera ambiguo | Consulta primero | Consulta de estado y luego decisión |
| Tarifa limitada | Sí | reintentar con retroceso |
| Error de infraestructura | Sí | Reintento de reloj + disyuntor |

## Distinciones frecuentemente confusas```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
```## Comparación rápida entre categorías

| Categoría | ¿Está claro el resultado? ¿Tiene sentido volver a intentarlo? Causa típica |
| --- | --- | --- | --- |
| Declive empresarial | Sí | No | Tarjeta, saldo, fraude |
| Tiempo de espera | No | Consulta primero | Red, lentitud de PSP |
| Tarifa limitada | Sí | Sí (esperando) | Control de volumen |
| Infraestructura | Sí | Sí | Mal funcionamiento del lado de PSP |

## Lista de verificación al configurar una taxonomía

1. ¿Cada código de error devuelto por el Proveedor se asigna claramente a una de las cuatro categorías?
2. Cuando llega un nuevo código de error no asignado, ¿el sistema consulta el estado de forma predeterminada o lo vuelve a intentar ciegamente? (Valor predeterminado verdadero: estado de la consulta).
3. En el escenario de tiempo de espera, ¿está realmente implementada la verificación de estado previa al reintento?
4. ¿El tiempo de espera para 429 tiene en cuenta el encabezado `Retry-After` de la PSP (si corresponde)?
5. ¿Se monitorea la frecuencia 5xx como una métrica que activará un disyuntor?
6. ¿El flujo de usuarios después del rechazo del negocio nunca ingresa al ciclo de reintento?

## Lo que debes recordar de este artículo

1. El 'fracaso' no es un estado único; Son cuatro realidades diferentes que requieren al menos cuatro acciones diferentes.
2. No se vuelve a intentar la declinación del negocio; El tiempo de espera no se reintenta a ciegas, se consulta primero.
3. 429 es una señal, 5xx es una falla; Ambos se vuelven a juzgar pero con diferente disciplina.
4. La taxonomía hace que el error sea legible desde su propia enumeración `failureReason`, no desde el texto sin formato del proveedor.

> Si se escribió una política de reintento sin entender el error; No sólo es inútil, sino que silenciosamente causa daño.

En la siguiente sección, configuraremos el algoritmo de reintento real para cada una de estas cuatro categorías: retroceso, fluctuación, límite y disyuntor.