> ## 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 de errores, códigos HTTP y reintentos seguros.

## Manejo de errores

Los errores devuelven un JSON con `detail`:

```json theme={"system"}
{ "detail": "Descripción del error" }
```

En validación (`422`), `detail` es un array con el campo que falló:

```json theme={"system"}
{
  "detail": [
    { "type": "missing", "loc": ["body", "gloss"], "msg": "Field required" }
  ]
}
```

***

## Códigos HTTP

| Código | Significado                                     | Qué hacer                                                                                                        |
| ------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `200`  | OK                                              | Procesar la respuesta.                                                                                           |
| `401`  | API key ausente o inválida                      | Enviar tu llave completa en el header `X-Api-Key`.                                                               |
| `404`  | QR no encontrado                                | El `qrId` no existe o pertenece a otro comercio. En `POST`, revisa la URL: `https://qrsimple.cucu.bo/api/v1/qr`. |
| `409`  | Request en curso con la misma `Idempotency-Key` | Reintentar en 1–2 s con la misma key.                                                                            |
| `422`  | Body inválido                                   | Leer `detail` y corregir el campo indicado.                                                                      |
| `502`  | La red de pagos no respondió                    | Reintentar con backoff y la misma `Idempotency-Key`.                                                             |
| `503`  | No se pudo registrar la solicitud               | Reintentar con la misma `Idempotency-Key`.                                                                       |

***

## Reintentos

Para `502` y `503`, backoff exponencial con jitter: 1 s → 2 s → 4 s → 8 s (máx. 4 intentos al crear).

<Warning>
  **Nunca reintentes** un `POST /qr` sin `Idempotency-Key`: puede generar cobros duplicados. Reintenta siempre con la misma key.
</Warning>