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.

¿Dudas? Escríbenos o escribe a soporte@businesslink.do.