> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de errores

> Estructura estándar de errores, tabla de códigos HTTP y estrategia de reintentos con backoff exponencial.

## Manejo de errores

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

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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)
```

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