Errores de API de facturación electrónica en LATAM: guía por país

Los errores de facturación electrónica en LATAM no se comportan como los errores de una API REST estándar. La mayoría de los rechazos no son errores del proveedor — son rechazos de la autoridad fiscal del país, devueltos al proveedor y reencaminados al ISV. El problema es que cada autoridad tiene su propio esquema de códigos, y los proveedores los traducen (o no los traducen) de formas muy distintas.

Esta guía documenta los errores más frecuentes por país — Colombia, República Dominicana, Panamá y Costa Rica — con sus causas y el proceso de diagnóstico. El objetivo es que cuando aparezca un error en producción, el equipo de desarrollo sepa dónde buscar sin necesidad de abrir un ticket.

Cómo leer un error de facturación electrónica

Un error de facturación electrónica bien estructurado debe identificar tres cosas: el origen del error (proveedor o autoridad fiscal), el campo afectado y la acción correctiva. Un error que solo dice “Documento rechazado” sin más contexto obliga al equipo a iniciar un diagnóstico desde cero. Un error que dice “Campo issuer.taxId: dígito de verificación incorrecto para el valor 900000000” permite corregir en segundos.

El primer paso de cualquier diagnóstico es identificar si el error viene del proveedor (validación de schema, formato del request) o de la autoridad fiscal (rechazo normativo del documento transmitido). Los errores del proveedor tienen códigos propios del proveedor; los errores de la autoridad fiscal vienen con los códigos oficiales del país.

Errores frecuentes en Colombia — DIAN

La DIAN devuelve errores en el XML de respuesta del Servicio Web de Facturación. Los rechazos más frecuentes en integraciones nuevas son: NIT con dígito de verificación incorrecto, CUFE mal calculado, firma XAdES-BES inválida o vencida, inconsistencias entre la tarifa de IVA declarada y el monto calculado, y número de resolución de facturación fuera de rango.

Errores típicos Colombia y su diagnóstico

// Error: NIT con dígito de verificación incorrecto
{
  "code": "FAD089B",
  "field": "AccountingSupplierParty.Party.PartyTaxScheme.CompanyID",
  "description": "El dígito de verificación del NIT no corresponde"
}
// Diagnóstico: calcular el dígito con el algoritmo oficial DIAN (módulo 11)

// Error: CUFE incorrecto
{
  "code": "FAD090B",
  "description": "El CUFE no corresponde con los datos del documento"
}
// Diagnóstico: verificar que los campos de entrada al SHA-384 coincidan exactamente
// con la fórmula del Anexo Técnico vigente

// Error: Resolución de facturación vencida
{
  "code": "FAD092B",
  "description": "La resolución de facturación está vencida o fuera de rango"
}
// Diagnóstico: verificar vigencia y rango de la resolución en el DIAN Muisca

Errores frecuentes en República Dominicana — DGII

Los errores de la DGII en el flujo de e-CF tienen una particularidad: llegan de forma asíncrona. El documento puede pasar las validaciones iniciales del PSFE y ser rechazado por la DGII minutos después. Los rechazos más frecuentes: RNC del emisor no registrado en la DGII, NCF fuera del rango autorizado, tipo de e-CF incorrecto para la operación declarada, RNC del comprador inválido en e-31, y campos de impuesto inconsistentes.

Errores típicos RD y su diagnóstico

// Error async: RNC del emisor no válido
{
  "dgiiCode": "1",
  "description": "RNC/Cédula del emisor no existe en el registro de la DGII"
}
// Diagnóstico: verificar el RNC en el portal de consulta pública de la DGII

// Error async: NCF fuera del rango autorizado
{
  "dgiiCode": "3",
  "description": "El NCF no está dentro del rango aprobado para este emisor"
}
// Diagnóstico: verificar el rango autorizado en el portal de la DGII
// o solicitar al proveedor el estado del rango de NCF

// Error async: Tipo e-CF inválido para la operación
{
  "dgiiCode": "5",
  "description": "El tipo de comprobante no corresponde con la operación declarada"
}
// Diagnóstico: revisar la tabla de tipos de e-CF del Anexo Técnico DGII
// y verificar que el tipo seleccionado corresponde con la naturaleza de la operación

Errores frecuentes en Panamá — DGI

La DGI Panamá rechaza documentos principalmente por problemas en el RUC del emisor o receptor, tipo de documento incorrecto para la operación, inconsistencias en los montos declarados y ausencia del CAFE en la representación gráfica. El error más común en integraciones nuevas es el RUC del receptor ausente en facturas de operación interna B2B.

Errores típicos Panamá y su diagnóstico

// Error: RUC de receptor ausente en tipo 01 (B2B)
{
  "code": "DGI-001",
  "field": "receiver.ruc",
  "description": "El RUC del receptor es obligatorio en facturas de operación interna B2B"
}
// Diagnóstico: agregar el RUC del receptor en el payload

// Error: CAFE ausente en la representación gráfica
{
  "code": "DGI-007",
  "description": "La representación gráfica no incluye el código QR con el CAFE"
}
// Diagnóstico: verificar que el PDF generado incluya el código QR con el CAFE
// Este campo es obligatorio en la representación gráfica del SFEP

// Error: Tipo de documento incorrecto para zona libre
{
  "code": "DGI-003",
  "description": "Operación en zona libre debe usar tipo 06, no tipo 01"
}
// Diagnóstico: verificar el tipo de operación y usar el tipo de documento correspondiente

Errores frecuentes en Costa Rica — Ministerio de Hacienda

Hacienda Costa Rica devuelve tres estados posibles: aceptado, aceptado-parcial y rechazado. Los rechazos más frecuentes en integraciones nuevas son: clave numérica mal formada (los 50 dígitos con alguno incorrecto), firma digital inválida o con certificado vencido, versión del XML-CR desactualizada, y montos de impuesto inconsistentes con la tarifa declarada.

Errores típicos Costa Rica y su diagnóstico

// Error: Clave numérica mal formada
{
  "ind-estado": "rechazado",
  "mensaje-hacienda": "La clave numérica no cumple con el formato establecido"
}
// Diagnóstico: verificar que la clave tenga exactamente 50 dígitos numéricos
// y que cada segmento corresponda con el esquema del Anexo Técnico de Hacienda

// Estado aceptado-parcial: campo de actividad económica desactualizado
{
  "ind-estado": "aceptado-parcial",
  "mensaje-hacienda": "El código de actividad económica no corresponde al código vigente"
}
// Diagnóstico: verificar el código CIIU actualizado en el ATV del emisor

// Error: Firma digital inválida
{
  "ind-estado": "rechazado",
  "mensaje-hacienda": "La firma del comprobante no es válida"
}
// Diagnóstico: verificar que el certificado .p12 esté vigente y corresponda
// al emisor registrado en Hacienda; solicitar renovación si está vencido

Cómo structurar el error handling en la integración

El error handling de una integración de facturación electrónica en LATAM debe considerar tres capas: errores de red y timeout (el request no llegó al proveedor), errores del proveedor (el documento no pasó la validación del proveedor) y errores de la autoridad fiscal (el documento llegó al proveedor pero fue rechazado por la autoridad). Cada capa requiere una estrategia de reintento distinta: los errores de red admiten reintento inmediato; los errores de la autoridad fiscal requieren corrección del documento antes de reintentar.

Preguntas frecuentes

¿Cuál es la diferencia entre un error 400 del proveedor y un rechazo de la autoridad fiscal?

Un error 400 del proveedor indica que el request no cumple con el schema de la API — campo faltante, formato incorrecto, tipo de dato inválido. El documento nunca llegó a la autoridad fiscal. Un rechazo de la autoridad fiscal puede llegar como 200 OK del proveedor (el request fue procesado correctamente) pero con un status de rechazo en el body — el documento llegó a la autoridad y fue rechazado por razones normativas. Confundir ambos lleva a estrategias de reintento incorrectas.

¿Cómo puedo identificar si un error es transitorio o definitivo en la DGII de RD?

Los errores transitorios de la DGII ocurren por indisponibilidad temporal del sistema y se identifican porque el e-CF permanece en estado “pending” durante un tiempo inusualmente largo o porque la DGII devuelve un código de error de sistema (generalmente códigos 99x). Los errores definitivos tienen códigos de validación específicos que indican que el documento fue evaluado y rechazado por incumplimiento normativo. Los primeros admiten reintento después de un tiempo; los segundos requieren corrección del documento.

¿Qué diferencia hay entre un aceptado-parcial de Hacienda y un rechazo en Costa Rica?

Un aceptado-parcial significa que Hacienda registró el comprobante y tiene validez fiscal, pero hay campos con observaciones no bloqueantes. El ISV debe registrar esas observaciones y corregirlas en futuros comprobantes porque pueden volverse rechazos en actualizaciones de las validaciones. Un rechazo significa que el comprobante no fue registrado en el ATV y no tiene validez fiscal — debe corregirse y retransmitirse. La diferencia es crítica: un aceptado-parcial no requiere reemisión, un rechazado sí.

¿Es posible diagnosticar errores de facturación electrónica sin acceso a los logs del proveedor?

Sí, con limitaciones. Si el proveedor expone el body completo de la respuesta de la autoridad fiscal en su API, el ISV puede diagnosticar directamente usando el Anexo Técnico del país correspondiente. Si el proveedor solo devuelve códigos propios sin el código original de la autoridad, el diagnóstico depende del catálogo de errores del proveedor. Por eso, solicitar ese catálogo antes de firmar es crítico: sin él, cualquier rechazo no documentado requiere abrir un ticket de soporte.

Para el contexto completo de evaluación de proveedores, consulta los 5 criterios técnicos para elegir una API de facturación en LATAM. Para entender cómo los sandboxes reproducen estos errores en ambiente de prueba, revisa la comparativa de sandboxes por país.