Guía de Solución de Problemas - API Factura Electrónica

Este artículo cubre los errores más comunes al integrar la API de Factura Electrónica de Dataico.

Para cada error encontrarás el mensaje exacto del response, la causa y la solución. Si necesitas más detalle, cada fila enlaza al artículo completo.

Sobre el código HTTP. Ante un error, lee siempre el arreglo errors del response: trae el mensaje y el campo (path) que falló. Un error de validación del documento puede llegar con código HTTP 500 sin que sea una caída del servidor. Los errores de autenticación responden 401.

Mensaje de error (response)	Causa	Solución rápida	Artículo completo
`{"errors": "No estás autorizado para usar esta cuenta de DATAICO, por favor revisa los datos de conexión 'Dataico Account Id' y 'Auth Token'."}` (HTTP 401)	El `Auth-token` no corresponde a ningún Auth Token ni llave API vigente: está mal copiado, tiene espacios, está incompleto o fue revocado.	Copiar de nuevo la credencial desde Opciones > Configuración (o crear una llave API) y verificar que no haya espacios al pegarla.	Error: No estás autorizado
`{"errors": "Tu API key expiró. Genera una nueva desde la configuración de tu empresa."}` (HTTP 401)	La llave API llegó a su fecha de vencimiento.	Crear una llave nueva en Opciones > Configuración, botón Llaves API, y reemplazarla en la integración.	¿Cómo crear y revocar llaves API?
`{"errors": [{"error": "Debe enviar un dataico account id válido (debe ser un uuid como a7ec34ae-f30b-40e8-b3a8-93bfc4c37d70)", "path": ["invoice"]}]}`	El `dataico_account_id` del cuerpo está vacío, es booleano, está mal copiado o es de una cuenta distinta a la del `Auth-token`.	Copiar el Dataico Account Id de la misma cuenta del `Auth-token` desde Opciones > Configuración y enviarlo como texto.	Error: Debe enviar un dataico account id válido
`"Ciudad 'X' es inválida para el departamento 'Y'."`	La ciudad (`city`) del cliente no pertenece al departamento (`department`) enviado.	Corregir `customer.city` y `customer.department`: ambos por nombre, o ambos por código (municipio de 3 dígitos y departamento de 2).	Error: Ciudad inválida para el departamento
`"El número para este documento '1' es inválido. Tiene que ser el siguiente número '3' para su numeración"`	La factura se envió con `numbering.flexible` en `false` y el número no es exactamente el siguiente de la numeración. Los números del mensaje van sin prefijo.	Enviar el número que indica el mensaje, o dejar `flexible` en `true` (valor por defecto).	Error: Números de factura inválidos
`"La fecha de pago debe ser igual o posterior a la fecha de emisión cuando payment_means_type es CREDITO"` (antes de septiembre de 2026, el mismo caso llegaba como `{"errors": [{"path": ["invoice"], "error": null}]}`)	En una factura a crédito, la `payment_date` cae en un día calendario anterior al de la `issue_date`. La comparación es por día: una hora distinta dentro del mismo día no produce el error.	Enviar la `payment_date` con la misma fecha de la `issue_date` o con una posterior.	Error: fecha de pago anterior a la fecha de emisión
`"Para una moneda distinta de COP se deben especificar currency_exchange_rate (tasa de cambio) y currency_exchange_rate_date (fecha de tasa de cambio)"`	La factura se emite en una moneda distinta de `COP` y no trae la tasa de cambio, su fecha, o ninguna de las dos.	Agregar `currency_exchange_rate` y `currency_exchange_rate_date` a la factura.	Error: falta la tasa de cambio en moneda extranjera
`{"errors":[{"error":"No se encuentra numeración '{\"prefix\" \"FEE\", \"resolution_number\" \"18760000001\"}' en la cuenta de DATAICO","path":["invoice"]}]}`	La cuenta de las credenciales no tiene una numeración con ese prefijo y resolución en el ambiente pedido (`env`).	Verificar en Ventas > Facturas > Numeraciones el prefijo y la resolución, y que `env` sea `PRUEBAS` para numeraciones de pruebas o `PRODUCCION` para las de producción.	Error: No se encuentra numeración
`"Solo puede modificar Factura 'FE10' si esta DIAN rechazada."`	Enviaste por `POST` un número que ya existe en Dataico y esa factura no está rechazada por la DIAN. (Si está aceptada, la API devuelve la factura existente; si está rechazada, la reemplaza.)	Usar un número nuevo, o consultar la factura existente con Consulta de factura por API.
`{"errors": [{"path": ["invoice", "charges", 0, "base_amount"], "error": "El campo es requerido"}]}`	El campo `charges` se envió como un objeto y no como un arreglo de objetos, así que la API no encuentra el `base_amount` de cada cargo.	Enviar `charges` como arreglo: `"charges": [{"reason": "PROPINA", "base_amount": 15000, "discount": false}]`.	Ver la sección al final de esta guía
`"Numero de documentos a crear '1' excede numero de documentos restantes en el plan."`	Se agotaron los documentos disponibles en el plan de la cuenta.	Revisar el plan en Dataico o escribirnos al chat de soporte para ampliarlo.
`{"errors": "Su empresa ha sido bloqueada."}` (HTTP 401)	La empresa está bloqueada en Dataico. Si es cliente de un aliado, el bloqueo puede venir de su aliado.	Si la empresa es cliente de un aliado, consulta primero con el aliado. Si no, escríbenos al chat de soporte.
`"El nombre del tercero es incorrecto."`	El cliente de la factura no trae el nombre que la DIAN exige para su tipo: `company_name` cuando `party_type` es `PERSONA_JURIDICA`, o `first_name` y `family_name` cuando es `PERSONA_NATURAL`. El `party_type` que envías reemplaza el que el cliente tenga guardado, así que un cliente creado como persona natural y enviado como jurídica necesita `company_name`.	Enviar el nombre que corresponde al `party_type` del cliente. La factura rechazada no consume consecutivo.

Error "El campo es requerido" en el base_amount de charges

Este error aparece cuando el campo charges (cargos adicionales, como una propina) se envía como un objeto en lugar de un arreglo de objetos. La API espera una lista y, al recibir un objeto, marca el base_amount como faltante, una vez por cada clave del objeto.

Estructura con el error:

"charges": {
  "reason": "PROPINA",
  "base_amount": 15000,
  "discount": false
}

Detalle (RESPONSE):

{
  "errors": [
    {"path": ["invoice", "charges", 0, "base_amount"], "error": "El campo es requerido"},
    {"path": ["invoice", "charges", 1, "base_amount"], "error": "El campo es requerido"},
    {"path": ["invoice", "charges", 2, "base_amount"], "error": "El campo es requerido"}
  ]
}

Estructura correcta:

"charges": [
  {
    "reason": "PROPINA",
    "base_amount": 15000,
    "discount": false
  }
]

reason: motivo del cargo (por ejemplo, PROPINA).
base_amount: monto base del cargo.
discount: true o false, según si el cargo es un descuento.

Corrige la estructura y reenvía el documento. Para ver una factura completa con propina, consulta la estructura FE Propina $.

¿El error no aparece en esta tabla? Consulta la Documentación Técnica de la API de Dataico o escríbenos al chat de soporte con el response completo.