Códigos de Error - API de Facturación Electrónica
Esta documentación detalla los códigos de error que pueden presentarse al utilizar la API de Facturación Electrónica. Para cada error se incluye el código, la descripción original en inglés, la causa en español y la solución recomendada.
Estructura de errores
Todos los errores de la API siguen una estructura común con un código, mensaje y detalles adicionales cuando corresponde.
Estructura de ejemplo de respuesta de error
{
"success": false,
"error": {
"message": "Error mapping receiver",
"details": [
"[RequiredField] The field Receiver->NIT is required"
]
"code": "BUSINESS_CCFMAPPER_ERROR"
}
}Errores Comunes
RequiredField
Descripción: The field %s is required
Causa: Un campo obligatorio no fue proporcionado en la solicitud.
Solución: Revisa la documentación para identificar los campos obligatorios y asegúrate de incluirlos en tu solicitud.
WithoutParams
Descripción: Parameters are expected but none were received
Causa: Se esperaban parámetros adicionales que no fueron proporcionados.
Solución: Verifica que estás enviando todos los parámetros requeridos por el endpoint.
ExceededParameters
Descripción: Error %s The required parameters have been exceeded, check the number of parameters sent, actual: %d
Causa: Se enviaron más parámetros de los necesarios.
Solución: Revisa la cantidad de parámetros enviados y elimina los que no son necesarios.
InvalidLength
Descripción: The field %s does not meet the required length, it must be %s characters, received %s
Causa: La longitud del campo no cumple con los requisitos especificados.
Solución: Ajusta la longitud del campo según los requisitos especificados en la documentación.
InvalidNumberRange
Descripción: The field %s does not meet the required length, it must be %s digits, received %s
Causa: El número no está dentro del rango permitido.
Solución: Verifica los límites del rango permitido y ajusta el valor.
InvalidFormat
Descripción: The field %s does not meet the required format, it must be %s, received %s
Causa: El formato del campo no es válido según las reglas establecidas.
Solución: Asegúrate de que el formato del campo cumple con las reglas especificadas en la documentación.
InvalidPattern
Descripción: The field %s does not meet the required pattern, it must be %s, received %s
Causa: El valor no coincide con el patrón requerido.
Solución: Revisa y ajusta el valor para que coincida con el patrón requerido.
InvalidField
Descripción: The field %s does not meet the defined business rules
Causa: El campo no cumple con las reglas de negocio definidas.
Solución: Revisa las reglas de negocio aplicables al campo y ajusta el valor en consecuencia.
InvalidDocumentNumber
Descripción: Invalid document number, must be: DUI with hyphen, NIT (with or without hyphen), or a document of 3-20 characters. Received: %s
Causa: El número de documento no cumple con el formato esperado.
Solución: El número de documento debe ser: DUI con guion, NIT (con o sin guion), o un documento de 3-20 caracteres.
NegativeDiscount
Descripción: The discount %s is negative
Causa: El descuento no puede ser un valor negativo.
Solución: Asegúrate de que el descuento sea un valor positivo o cero.
ExcessiveDiscount
Descripción: The discount %s is greater than the subtotal %s
Causa: El descuento es mayor que el subtotal, lo cual no es válido.
Solución: Asegúrate de que el descuento no supere el subtotal.
NegativeTaxedAmount
Descripción: The taxed sale %s is negative
Causa: La venta gravada no puede ser un valor negativo.
Solución: Asegúrate de que las ventas gravadas tengan valores positivos o cero.
ExcessiveTaxedAmount
Descripción: The taxed sale %f is greater than the price * quantity %f
Causa: La venta gravada excede el producto de precio por cantidad.
Solución: Verifica que la venta gravada no sea mayor que el precio multiplicado por la cantidad.
InvalidValue
Descripción: The value %d is not valid, it must be %s for field %s
Causa: El valor proporcionado no es válido para el campo especificado.
Solución: Revisa los valores permitidos para el campo y ajusta la entrada.
InvalidEmail
Descripción: The email %s is not valid. It must be a valid, existing email address and must be at least 3 characters long and no longer than 100
Causa: El correo electrónico no es válido o no cumple con los requisitos de longitud.
Solución: Proporciona una dirección de correo válida con una longitud entre 3 y 100 caracteres.
Errores de Identificación
InvalidVersion
Descripción: The version %s is not valid, it must be a number between 1 and 3
Causa: La versión debe ser un número entre 1 y 3.
Solución: Asegúrate de que el campo de versión contenga un valor válido (1, 2 o 3).
InvalidAmbientCode
Descripción: The ambient code %s is not valid, it must be: 00 -> (Testing) and 01 -> (Production)
Causa: El código de ambiente debe ser 00 (pruebas) o 01 (producción).
Solución: Utiliza "00" para el ambiente de pruebas o "01" para el ambiente de producción.
InvalidDateTime
Descripción: The date %s is not valid, it must be a date less than or equal to the current date
Causa: La fecha no es válida, debe ser una fecha igual o anterior a la fecha actual.
Solución: Verifica que la fecha proporcionada no sea futura.
Errores Temporales
InvalidEmissionTime
Descripción: The emission time %s is not valid, it must be a time less than or equal to the current time
Causa: La hora de emisión no es válida, debe ser una hora igual o anterior a la hora actual.
Solución: Verifica que la hora de emisión no sea futura.
InvalidTransmissionType
Descripción: The transmission type %s is not valid, it must be: 1 -> (Normal) and 2 -> (Contingency)
Causa: El tipo de transmisión debe ser 1 (normal) o 2 (contingencia).
Solución: Utiliza "1" para transmisión normal o "2" para contingencia.
Errores Monetarios
InvalidAmount
Descripción: The amount %s is not valid, it must be a number between 0 and 99999999999.99
Causa: El monto no es válido, debe estar entre 0 y 99,999,999,999.99.
Solución: Asegúrate de que el monto esté dentro del rango válido.
InvalidQuantity
Descripción: The quantity %s is not valid, it must be a number between 1 and 99999999999.99
Causa: La cantidad no es válida, debe estar entre 1 y 99,999,999,999.99.
Solución: Asegúrate de que la cantidad esté dentro del rango válido.
InvalidDiscount
Descripción: The discount %s is not valid, it must be a number between 0 and 100
Causa: El descuento no es válido, debe estar entre 0 y 100.
Solución: Asegúrate de que el descuento esté dentro del rango válido.
InvalidTax
Descripción: The tax %s is not valid, it must be a number between 0 and 99999999999.99
Causa: El impuesto no es válido, debe estar entre 0 y 99,999,999,999.99.
Solución: Asegúrate de que el impuesto esté dentro del rango válido.
InvalidCurrency
Descripción: The currency %s is not valid, it must be USD
Causa: La moneda debe ser USD.
Solución: Utiliza "USD" como valor para el campo de moneda.
InvalidItemType
Descripción: The item type %s is not valid, it must be: 1 -> (Product), 2 -> (Service), 3 -> (Both) and 4 -> (Tax)
Causa: El tipo de ítem debe ser 1 (producto), 2 (servicio), 3 (ambos) o 4 (impuesto).
Solución: Utiliza uno de los valores válidos para el tipo de ítem.
InvalidTaxType
Descripción: The tax type %s is not valid, it must be within the allowed tax catalog
Causa: El tipo de impuesto no está dentro del catálogo permitido.
Solución: Verifica el catálogo de tipos de impuesto permitidos y utiliza uno válido.
Errores de Ubicación
InvalidMunicipality
Descripción: Invalid municipality code %s for department %s. Municipality code must be a two-digit number that follows the official catalog pattern. For example, valid codes for this department include: %s. Please refer to the official municipality catalog.
Causa: El código de municipio no es válido para el departamento especificado.
Solución: Consulta el catálogo oficial de municipios y utiliza un código válido para el departamento correspondiente.
InvalidEstablishmentType
Descripción: The establishment type %s is not valid, it must be: 01 -> (Headquarters), 02 -> (Branch), 04 -> (Warehouse), 07 -> (Property or Yard) and 20 -> (Other)
Causa: El tipo de establecimiento no es válido.
Solución: Utiliza uno de los tipos de establecimiento válidos: 01 (Sede), 02 (Sucursal), 04 (Bodega), 07 (Propiedad o Patio) o 20 (Otro).
Errores del Documento Tributario Electrónico (DTE)
InvalidTotalAmount
Descripción: The total amounts do not match. Calculated total: %f, declared total: %f
Causa: Los montos totales no coinciden con el cálculo esperado.
Solución: Verifica que el total declarado coincida con el total calculado.
InvalidPaymentTotal
Descripción: The total payments (%f) do not match the operation amount (%f)
Causa: El total de pagos no coincide con el monto de la operación.
Solución: Asegúrate de que la suma de todos los pagos coincida con el monto total de la operación.
InvalidTotalIVA
Descripción: The total IVA %f does not match the sum of IVA taxes %f
Causa: El total de IVA no coincide con la suma de los impuestos IVA.
Solución: Verifica que el total de IVA declarado sea igual a la suma de todos los impuestos IVA calculados.
InvalidTotalTaxed
Descripción: The total taxed %f does not match the sum of taxed taxes %f
Causa: El total gravado no coincide con la suma esperada.
Solución: Asegúrate de que el total gravado declarado coincida con la suma de todos los elementos gravados.
InvalidTaxedAmount
Descripción: The taxed sale %f does not match the taxable base %f
Causa: La venta gravada no coincide con la base imponible.
Solución: Verifica que el monto de venta gravada sea igual a la base imponible.
InvalidTotalDiscount
Descripción: The total discounts %f do not match the sum of discounts %f
Causa: El total de descuentos no coincide con la suma de descuentos individuales.
Solución: Verifica que el total de descuentos declarado sea igual a la suma de todos los descuentos aplicados.
UnsupportedTaxCode
Descripción: Unsupported tax code %s, must be in the allowed tax catalog
Causa: El código de impuesto no está en el catálogo permitido.
Solución: Utiliza únicamente códigos de impuesto que estén en el catálogo permitido.