# Errores e idempotencia

## Formato de error (siempre el mismo)

```json
{"error": {"codigo": "documento_invalido", "mensaje": "Una factura de credito fiscal (E31) requiere el RNC o cedula del comprador.", "sugerencia": "Si el cliente no tiene RNC, use tipo_ecf 32 (consumo).", "campo": "comprador.rnc", "detalles": [], "request_id": "..."}}
```

Los mensajes están en español y son accionables: lea `sugerencia`, corrija y reintente. Los agentes de IA pueden autocorregirse con ellos. Cite `request_id` al pedir soporte.

## Códigos frecuentes

| Código | HTTP | Qué hacer |
|---|---|---|
| `clave_revocada`, clave inválida | 401 | Cree una clave nueva en el portal. |
| `permiso_insuficiente` | 403 | La clave no tiene ese permiso; cree otra con el permiso. |
| `llamada_desde_navegador` | 403 | Llame desde un servidor, no desde el navegador. |
| `documento_invalido` | 422 | Falta o sobra un campo; vea `campo` y `sugerencia`. |
| `filtro_invalido` | 422 | Un parámetro de consulta es incorrecto. |
| `rnc_invalido` | 422 | Un RNC tiene 9 dígitos y una cédula 11. |
| `rnc_no_encontrado` | 404 | El número no está en el directorio de la DGII. |
| `factura_no_encontrada` | 404 | Revise el e-NCF y el modo (`test` vs `live`). |
| `recibido_no_encontrado` | 404 | Revise el RNC del proveedor y el e-NCF. |
| `nota_excede_original` | 422 | Una nota de crédito no puede devolver más de lo facturado. |
| `confirmacion_requerida` | 400 | Envíe `confirmar: true`. |
| `servicio_no_disponible` | 503 | Reintente con el mismo `Idempotency-Key`. |

## Idempotencia

`POST /v1/facturas` y `POST /v1/ecf` exigen `Idempotency-Key` (un valor único por factura, por ejemplo un UUID).

- Mismo valor y mismo documento: recibe la misma respuesta (cabecera `Idempotent-Replayed: true`) y **nunca** se emiten dos comprobantes.
- Mismo valor y documento distinto: error de conflicto; use otra clave.
- Un timeout no significa que falló: reintente con el **mismo** valor.
