# Manejo de errores

Integrar una API en producción implica manejar fallos de red, validaciones y reglas de negocio.
Esta guía te ayuda a interpretar los errores de **QRwey!** y definir una estrategia estable
de reintentos, mensajes al usuario y registro para soporte.

## Principios

1. **No todos los errores se reintentan.**
Reintentar un `4xx` suele ser un error (excepto casos muy específicos).
2. **Distingue entre fallos temporales y definitivos.**
`5xx` y timeouts suelen ser temporales. `4xx` suelen ser definitivos.
3. **Registra contexto suficiente para soporte.**
Incluye endpoint, `Idempotency-Key` (si aplica), timestamps y cuerpo del error.


## Formato de error

Dependiendo del endpoint, QRwey! puede devolver un JSON con campos como:

- `code`: identificador del error
- `message`: descripción legible
- `details`: información adicional (si aplica)


> Si tu integración depende del contenido del error, usa `code` como clave estable
y evita parsear textos libres en `message`.


## Tabla de errores comunes

| Código HTTP | Qué significa | Qué hacer |
|  --- | --- | --- |
| `400 Bad Request` | Validación: campos faltantes, tipos inválidos, firma/params incorrectos | Corrige request, no reintentar |
| `401 Unauthorized` | API Key inválida o ausente | Verifica `X-API-Key` y ambiente |
| `404 Not Found` | QR inválido / no existe / revocado | Tratar como “QR inválido” |
| `409 Conflict` | Operación en conflicto: QR ya consumido o idempotencia | No reintentar; mostrar “ya utilizado” |
| `410 Gone` | QR expirado | Solicitar generar un QR nuevo |
| `422 Unprocessable Entity` | Regla de negocio/configuración fiscal | Revisar `code` y `message` |
| `429 Too Many Requests` | Límite de tasa (si aplica) | Esperar y reintentar con backoff |
| `500–599` | Error interno temporal | Reintentar con backoff y límite |


## Errores por endpoint

### Generar QR (`POST /api/v1/qrs`)

Errores típicos:

- `400`: request inválido (campos fiscales, `expires_at`, etc.)
- `401`: API Key inválida
- `409`: conflicto por idempotencia o duplicado lógico
- `422`: configuración fiscal incompleta o reglas no cumplidas
- `5xx`: error temporal


Acción recomendada:

- Si hay timeout/5xx → reintentar con el **mismo `Idempotency-Key`**
- Si hay `4xx` → corregir request / configuración, no reintentar en loop


### Resolver QR (`GET /api/v1/qrs`)

Errores típicos:

- `400`: `v/t/m` inválidos o firma incorrecta
- `404`: token no encontrado / revocado
- `409`: QR ya consumido (si aplica)
- `410`: QR expirado
- `422`: regla de negocio


Acción recomendada:

- `410` → pedir al comercio generar un QR nuevo
- `409` → mostrar “QR ya utilizado”
- `404` → mostrar “QR inválido”
- `400` → revisar extracción de parámetros desde `qr_content`


## Estrategia de reintentos (recomendada)

### Reintentar SOLO si:

- Timeout (sin respuesta)
- `500–599`
- `429` (si aplica)


### No reintentar si:

- Cualquier `400–499` (salvo `429`)
- `409` (conflicto) sin revisar lógica
- `410` (expirado)
- `404` (no encontrado)


## Backoff recomendado

Para reintentos temporales:

- 1er retry: 1s
- 2do retry: 2s
- 3er retry: 4s
- 4to retry: 8s


Límite recomendado:

- Máximo 3–5 reintentos
- Máximo 30s de ventana total


## Mensajes al usuario final (MX, sugeridos)

Evita mostrar mensajes técnicos como “410 Gone”. Mejor:

- `410`: **“Este QR ya expiró. Solicita uno nuevo.”**
- `409`: **“Este QR ya fue utilizado.”**
- `404`: **“QR inválido. Verifica el código e inténtalo de nuevo.”**
- `401`: **“No se pudo validar la solicitud.”** (solo si aplica al comercio)


## Logging y trazabilidad

Recomendación mínima de logs por request:

- Método + path (sin exponer tokens completos)
- Timestamp inicio/fin
- Código HTTP
- `Idempotency-Key` (si aplica)
- Resumen de `code` y `message` del error


> Evita loguear `t` y `m` completos; si necesitas trazabilidad, loguea solo un hash o una versión truncada.


## Checklist para producción

- [ ] Manejas explícitamente `404`, `409`, `410`, `422`
- [ ] Reintentas solo en timeouts y `5xx`
- [ ] Reusas el mismo `Idempotency-Key` en reintentos
- [ ] Mensajes al usuario son claros y no técnicos
- [ ] Logs suficientes sin exponer secretos


## ¿Qué sigue?

- Reintentos seguros: [Idempotencia & Reintentos](/guides/idempotency)
- Flujo completo: [Quickstart](/guides/quickstart)
- Detalle de endpoints y schemas: [Referencia del API](/apis/qrwey)