Errores Frecuentes en Factura Electrónica v4.4 Costa Rica

Los errores que devuelve Hacienda al rechazar un documento v4.4 tienen códigos específicos. Una vez identificados, el diagnóstico baja de horas a minutos. Pero la primera vez que aparecen en producción suelen detener la operación porque el equipo no conoce el catálogo de causas frecuentes ni los patrones de validación local que los habrían prevenido. Conocer esos errores antes de la migración es lo que diferencia una transición estable de una con horas de inactividad.

Esta guía recorre los errores más frecuentes de v4.4 en producción, qué causa cada uno, cómo diagnosticarlos sin recurrir al soporte del proveedor tecnológico, y qué validaciones locales conviene implementar para prevenirlos antes de transmitir.

Categorías de errores en v4.4

Errores de XSD (rechazo sintáctico)

Hacienda valida primero la estructura del XML contra el XSD oficial v4.4. Errores en este nivel — elementos faltantes, atributos mal formados, namespaces incorrectos — producen rechazo inmediato. La validación no llega a evaluar reglas de negocio. Diagnosticar es sencillo porque el error apunta al elemento exacto: validar el XML construido contra el XSD localmente antes de transmitir captura la mayoría de estos casos.

Errores de validación de negocio

Si el XML es estructuralmente válido, Hacienda ejecuta validación de negocio sobre el contenido: coherencia de totales, vigencia de la firma, identificación correcta del receptor, códigos del catálogo vigente. Estos errores se devuelven con un código específico que apunta a la causa concreta. Conocer el catálogo de errores acelera el diagnóstico significativamente.

Errores frecuentes específicos

Identificación del receptor inválida

Es el error más frecuente en producción. Causas habituales: cédula con dígito verificador mal calculado, identificación con formato no coherente con el tipo declarado (por ejemplo, cédula jurídica declarada como física), pasaporte sin código de país. Prevención: validar localmente el formato del identificador y el dígito verificador antes de transmitir, contra las reglas del catálogo Hacienda v4.4.

Cálculo de impuestos incoherente

Hacienda rechaza cuando la suma de impuestos discriminados por línea no coincide con el total de impuestos declarado, o cuando el total a pagar no cuadra con la base más los impuestos por décimas. La causa habitual es aritmética de punto flotante en el cálculo. Prevención: usar tipos decimales precisos (BigDecimal en Java, Decimal en Python, equivalentes en otros lenguajes); redondear al final del cálculo, no en pasos intermedios.

Código de tarifa fuera del catálogo vigente

El catálogo de tarifas de IVA y otros impuestos se actualiza periódicamente por Hacienda. Usar un código de la versión anterior genera rechazo. Causa habitual: sistema con catálogo desactualizado en su base de datos local. Prevención: sincronizar el catálogo de Hacienda mensualmente como mínimo, o usar un proveedor tecnológico que lo mantenga sincronizado del lado del servidor.

Clave del documento duplicada

La clave de 50 caracteres del documento electrónico debe ser única para el emisor. Hacienda rechaza cuando recibe un documento con clave ya registrada. Causa habitual: reintento de transmisión donde la primera vez sí llegó pero el sistema no recibió el acuse y reintentó con la misma clave. Prevención: consultar el estado del documento por clave antes de reintentar, en lugar de retransmitir ciegamente.

Firma XAdES inválida

Hacienda rechaza cuando la firma XAdES no verifica correctamente. Causas: canonicalización inclusiva en lugar de exclusiva, algoritmo de hash incorrecto, certificado vencido o no registrado, reloj del servidor desincronizado. Prevención: validar la firma localmente con xmlsec1 contra el certificado público de Hacienda antes de transmitir.

Para equipos que prefieren no construir todo el catalog de validaciones locales para cada cambio de Hacienda, la API de facturación electrónica para Costa Rica de Alanube ejecuta las validaciones del lado del servidor antes de transmitir a Hacienda, devolviendo los errores con el detalle del campo problemático antes de generar la transmisión oficial — lo cual elimina la mayoría de rechazos en producción.

Diagnóstico paso a paso de un rechazo

Capturar la respuesta completa

El primer paso siempre es loguear la respuesta completa de Hacienda, no solo el estado. La descripción del error suele incluir el campo problemático, el valor enviado y el valor esperado. Sin ese detalle, el diagnóstico se vuelve adivinar; con ese detalle, suele bastar para corregir directamente. Para sistemas en producción, conviene almacenar las respuestas completas en logs persistentes para auditorías posteriores.

Reproducir en staging

Una vez identificado el código, intentar reproducir el escenario en staging con el mismo payload (sustituyendo el receptor real por uno sintético). Si reproduce, el problema es del XML construido y se aísla en el código de generación. Si no reproduce, el problema es de datos específicos del receptor o de la operación — conviene revisar la entrada del usuario o la fuente de datos.

Validación local antes de retransmitir

Antes de retransmitir después de un rechazo, ejecutar las validaciones locales que Hacienda aplica del lado servidor: validar XML contra XSD v4.4, recalcular la clave desde el XML construido, verificar suma de totales, validar formato del identificador del receptor. Si alguna falla localmente, hay alta probabilidad de que el rechazo se repita. Si todas pasan, el reintento tiene sentido.

Patrones de validación local recomendados

Validar XML contra XSD v4.4

Validar el XML contra el XSD oficial v4.4 antes de transmitir captura el 30% al 50% de los errores. La validación con xmllint o equivalente toma milisegundos y se incorpora fácilmente al pipeline de emisión. Cualquier error sintáctico aparece localmente con el path exacto del elemento, lo cual acelera el diagnóstico antes de la transmisión.

Recalcular la clave desde el XML

Después de construir el XML y antes de transmitir, recalcular la clave del documento desde el XML construido y compararla con la clave embebida. Si no coinciden, hay un bug entre la lógica de cálculo y la serialización del XML, y se detecta antes del rechazo en producción.

Verificar coherencia matemática de totales

La suma de precios unitarios por cantidad debe igualar el subtotal. El subtotal más impuestos debe igualar el total a pagar. Las diferencias por aritmética de punto flotante deben corregirse con redondeo al final del cálculo. Validar esto antes de transmitir captura el error frecuente de "diferencia de céntimos" que Hacienda rechaza sin tolerancia.

La documentación pública de Alanube mantiene un catálogo actualizado de códigos de error de Hacienda Costa Rica con su causa y la regla de validación local recomendada, lo cual sirve como referencia rápida cuando aparece un rechazo nuevo en producción.

Preguntas frecuentes

¿Cuál es la diferencia entre rechazo por error sintáctico y rechazo por error de negocio en Hacienda? El rechazo por error sintáctico se produce cuando el XML enviado no cumple el XSD v4.4: estructura malformada, elementos requeridos faltantes, namespaces incorrectos. Aparece en el primer paso de validación, antes de evaluar reglas de negocio. El rechazo por error de negocio se produce cuando el XML sí cumple el XSD pero las reglas tributarias detectan inconsistencias: cálculo de impuestos incorrecto, código de tarifa fuera del catálogo, receptor con identificación inválida. El primero apunta al constructor del XML; el segundo apunta al contenido o a los datos del receptor.

¿Cómo puedo identificar qué campo del XML está causando el rechazo cuando el código de error es genérico? Dos técnicas. Primera: validar el XML contra el XSD localmente — cualquier error sintáctico aparece con el path exacto del elemento problemático. Segunda: hacer bisección del payload — reducir el XML al mínimo que reproduce el error agregando campos uno a uno hasta encontrar el problemático. La segunda técnica es útil cuando el código de error es genérico y el XSD no lo captura, especialmente cuando se trata de reglas de negocio que dependen de combinaciones de campos.

¿Qué diferencia hay entre los errores que aparecen en staging y los que aparecen en producción? El validador de Hacienda es funcionalmente idéntico en ambos ambientes — los errores técnicos (XSD, firma, clave, totales) son los mismos. La diferencia está en los datos: en staging los receptores son sintéticos y los rechazos por identificación inválida se evitan. En producción el universo de receptores es real y aparecen rechazos por identificación mal capturada, dígito verificador incorrecto o receptor no encontrado. También aparecen en producción errores por tarifa de IVA mal mapeada para el sector del receptor, lo cual no se captura en staging.

¿Es posible automatizar el reintento de transmisiones rechazadas sin generar duplicados? Sí, con cuidado. El reintento automático solo es seguro para errores donde la causa se puede corregir programáticamente sin intervención humana: timeout del endpoint Hacienda, error 5xx transitorio del PT, rate limit alcanzado. Para esos casos, retry con backoff exponencial funciona. Para errores de contenido (identificación inválida, cálculo incorrecto, código de tarifa obsoleto), el reintento automático genera la misma falla — conviene marcar el documento como pendiente de revisión manual. Distinguir entre errores transitorios y errores de contenido es la condición para que la automatización no produzca duplicados o ruido innecesario.

Errores Frecuentes en Factura Electrónica v4.4 Costa Rica y Cómo Resolverlos