Errores y rechazos

Hay dos clases de fallo y conviene no confundirlas. Un error de la API llega en la respuesta HTTP: la petición no se acepto y nada se emitió. Un rechazo de la DGII llega después, en el campo error_message del documento, casi siempre con el e-NCF ya consumido.

Errores de la API

1. Errores de dominio

Los que produce la lógica de documentos. Son los únicos que traen un código legible por máquina.

{
  "success": false,
  "error": {
    "code": "INVALID_TOTALS",
    "message": "total (5800.00) does not match subtotal + itbis (5900.00).",
    "field": "totals.total"
  }
}

field aparece solo cuando el error se puede atribuir a un campo concreto.

Dos mensajes de esta familia merecen leerse completos porque te dicen exactamente qué hacer:

{
  "success": false,
  "error": {
    "code": "INVALID_DOCUMENT_STATE",
    "message": "The DGII already consumed this e-NCF, so resending it will only be rejected as a duplicate. Discard this document and submit the corrected data instead."
  }
}

Y al descartar un rechazado, la respuesta te recuerda que el reenvío necesita un external_ref nuevo:

{
  "success": true,
  "data": { "ulid": "01JZ8K4QM2N5P7R9T1V3W5X7Y9", "encf": "E310000000001", "discarded": true },
  "message": "Rejected document discarded. e-NCF E310000000001 can be submitted again with a distinct external_ref."
}

2. Errores de validación

Formato estandar de Laravel, con todos los campos que fallaron:

{
  "message": "The type field is required. (and 2 more errors)",
  "errors": {
    "type": ["The type field is required."],
    "items": ["The items field is required."],
    "totals.total": ["The totals.total field is required."]
  }
}

3. Errores de autenticación y de plan

4. Errores del servidor

{
  "message": "Server Error"
}

Reintenta con espera creciente. Si un POST /api/v1/documents devuelve 500 o se corta por timeout, no lo repitas a ciegas: consulta primero por tu external_ref si el documento ya existe. Si lo mandaste con external_ref, repetirlo es seguro y te devolverá el original.

Rechazos de la DGII

Estos no vienen en la respuesta HTTP: aparecen en error_message cuando el documento pasa a rejected, y llegan por webhook o al consultarlo. El texto es casi siempre el de la DGII, palabra por palabra.

Rechazos que genera FiscalFlow antes de llegar a la DGII

Cuando FiscalFlow detecta que el documento no puede ser aceptado, lo rechaza el mismo, sin gastar el envío. En ese caso error_code viene relleno:

Estos mensajes son largos a propósito y dicen qué configurar. El de expiration_date, por ejemplo, nombra el campo, el formato y la pantalla de Odoo donde se configura, precisamente porque el rechazo 145 que produciría la DGII no diría nada de eso.

Cuando se agotan los intentos

{
  "status": "rejected",
  "attempts": 5,
  "error_message": "Max attempts reached. Last error: DGII returned HTTP 503: ...",
  "error_code": null
}

Esto no es un rechazo de la DGII: es que no se pudo entregar tras cinco intentos repartidos en unas siete horas. Comprueba el estado de la DGII con GET /api/v1/dgii/status y, cuando esté disponible, descarta el documento y envíalo de nuevo.

Estrategia de reintentos

Estado de la DGII

Antes de dar por perdida una integración, comprueba si el problema es de la DGII. Este endpoint es público y no necesita key:

curl https://api.fiscalflowsupport.com/api/v1/dgii/status

{
  "success": true,
  "data": {
    "environments": {
      "testecf": { "status": "online", "latency_ms": 143, "checked_at": "2026-08-14T15:00:00+00:00" },
      "certecf": { "status": "online", "latency_ms": 150, "checked_at": "2026-08-14T15:00:00+00:00" },
      "ecf": { "status": "offline", "latency_ms": null, "checked_at": "2026-08-14T15:00:00+00:00" }
    },
    "overall": "degraded"
  }
}

Las caídas de la DGII son habituales, sobre todo en ventanas de mantenimiento. FiscalFlow reintenta solo, así que un documento en processing durante una caída no está perdido.