Manejo de errores

Los errores devuelven un JSON con detail:

{ "detail": "Descripción del error" }

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

{
  "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`.

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

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