Errores e idempotencia
Formato de error (siempre el mismo)
{"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.