Skip to main content

​
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ódigoNombreAcción recomendada
200OKÉxito. Procesar la respuesta.
400Bad RequestRevisar el payload enviado.
401UnauthorizedVerificar que el token es correcto y no expiró.
403ForbiddenEl recurso no pertenece a este comercio.
404Not FoundEl transactionId no existe o pertenece a otro comercio.
409ConflictRequest concurrente en curso. Reintentar en 1–2 s.
422Unprocessable EntityValidación fallida. Leer detail para corregir.
502Bad GatewayError transitorio en red de pagos. Reintentar con backoff exponencial.
503Service UnavailableSistema 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.