Manejo de errores - CUCU API

Manejo de errores

Todos los errores siguen la estructura estándar de FastAPI/JSON:

{
  "detail": "Descripción del error legible por humanos"
}

Para errores de validación (422), el campo detail es un array con el detalle por campo:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "amount"],
      "msg": "Input should be greater than or equal to 0",
      "input": "-5.00"
    }
  ]
}

Tabla de códigos HTTP

Código	Nombre	Acción recomendada
`200`	OK	Éxito. Procesar la respuesta.
`400`	Bad Request	Revisar el payload enviado.
`401`	Unauthorized	Verificar que el token es correcto y no expiró.
`403`	Forbidden	El recurso no pertenece a este comercio.
`404`	Not Found	El `transactionId` no existe o pertenece a otro comercio.
`409`	Conflict	Request concurrente en curso. Reintentar en 1–2 s.
`422`	Unprocessable Entity	Validación fallida. Leer `detail` para corregir.
`502`	Bad Gateway	Error transitorio en red de pagos. Reintentar con backoff exponencial.
`503`	Service Unavailable	Sistema momentáneamente no disponible. Reintentar.

Estrategia de reintentos recomendada

Para errores 502 y 503, aplicar backoff exponencial con jitter:

intento 1: esperar 1 s
intento 2: esperar 2 s
intento 3: esperar 4 s
intento 4: esperar 8 s  (máx. 4 intentos para requests de creación)

Nunca reintentar directamente un POST /transfers/qr sin Idempotency-Key — puede generar cobros duplicados. Siempre incluir la key y reintentar con la misma.