Errores de API en nómina electrónica DIAN: diagnóstico y solución para integradores

Por Ing. Carlos Méndez | 2 de septiembre de 2026

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.

El documento fue enviado al OASF. El OASF retornó código de error. El error dice 'documento inválido'. Sin más contexto. El desarrollador abre el ApplicationResponse en XML, busca el campo de descripción, encuentra un número de error que no está en la documentación del OASF, y empieza a buscar en foros. Este escenario se repite en cada nueva integración de nómina electrónica DIAN.

Este artículo documenta los errores más frecuentes en la integración de nómina electrónica DIAN vía API, organizados por categoría, con su causa exacta y la solución correspondiente. La clasificación ayuda a diagnosticar rápidamente dónde está el problema: en el XML generado, en la firma, en el OASF, o en la capa de transporte.

Cómo llegan los errores de la DIAN al integrador

Los errores de validación de la DIAN llegan al integrador a través de la ApplicationResponse: un XML firmado por la DIAN que contiene el estado del documento (aprobado o rechazado) y, en caso de rechazo, la lista de errores con código y descripción. El OASF es responsable de retornar esta ApplicationResponse al software integrador. Algunos OASFs retornan la ApplicationResponse completa en base64; otros solo retornan el código de estado y una descripción simplificada.

El integrador debe parsear la ApplicationResponse para extraer los errores. Los campos relevantes están en el elemento cbc:Note del ApplicationResponse XML, donde la DIAN incluye el código de error y la descripción en formato estructurado. Un OASF que solo retorna un código HTTP 400 sin el XML completo de la ApplicationResponse está ocultando información crítica para el diagnóstico.

Categoría 1: errores de esquema XML (XSD)

Los errores de esquema son los primeros en detectarse porque ocurren antes de que la DIAN evalúe las reglas de negocio. El documento no supera la validación contra el XSD. Estos errores tienen solución directa una vez identificado el campo incorrecto.

Elemento obligatorio ausente (XSD error: cvc-complex-type): el error indica que falta un elemento requerido. La causa más común es omitir el elemento Basico en Devengados, o faltar un atributo obligatorio como SuelDia o TraDur. Solución: revisar el XSD de la DIAN para el elemento indicado en el mensaje de error y agregar el campo faltante.

Tipo de dato incorrecto (XSD error: cvc-datatype-valid): el valor de un campo no corresponde al tipo esperado. Ejemplo: un campo de fecha con formato 'dd/mm/yyyy' en lugar de 'yyyy-mm-dd', o un monto con coma decimal en lugar de punto. Solución: normalizar los valores según los tipos del XSD antes de generar el XML.

Valor fuera del rango permitido (XSD error: cvc-pattern-valid): el campo tiene un patrón regex en el XSD que el valor no cumple. Ejemplo: el campo Periodo solo acepta los valores enumerados (MENSUAL, QUINCENAL, SEMANAL, etc.) — enviar 'mensual' en minúsculas genera este error. Solución: usar exactamente los valores del enum del XSD.

Categoría 2: errores de reglas de negocio DIAN

Los errores de reglas de negocio ocurren cuando el XML es válido en esquema pero viola una restricción de la DIAN. Son más difíciles de detectar previamente porque requieren conocer las reglas implícitas del sistema. Estos errores llegan con códigos específicos en la ApplicationResponse.

CUNE calculado incorrectamente: la DIAN recalcula el CUNE y lo compara con el declarado en el XML. Si difieren, el documento es rechazado. Las causas más frecuentes: valores monetarios formateados con separadores de miles al concatenar, orden de campos incorrecto, o ambiente equivocado (usar '1' para ambiente de pruebas cuando el XSD espera '2' para sandbox). Solución: verificar la fórmula de concatenación y usar valores numéricos crudos sin formateo.

DevengadosTotal no coincide con la suma de elementos: la DIAN suma internamente todos los elementos de Devengados y compara con DevengadosTotal. Una diferencia de cualquier valor genera rechazo. Causa frecuente: redondeo inconsistente entre el total calculado y los elementos individuales. Solución: calcular DevengadosTotal como suma exacta de los valores de los elementos que se incluirán en el XML, no como cálculo independiente.

AuxTransporte para trabajador con salario > 2 SMMLV: la DIAN verifica que el salario declarado en Basico (SuelDia × 30) no supere el tope de 2 SMMLV del año vigente cuando el AuxTransporte está presente. Solución: el software debe calcular el salario mensual del trabajador y condicionar la inclusión del AuxTransporte.

NIDD duplicada (mismo CUNE ya registrado): si el software envía dos veces el mismo documento (mismo CUNE), la DIAN rechaza el segundo envío. Esto ocurre cuando el sistema de reintentos no verifica si el primer envío fue ya aprobado. Solución: antes de reintentar, consultar el estado del documento por CUNE en el OASF.

Categoría 3: errores de firma digital

Los errores de firma son los más opacos porque el mensaje de rechazo es genérico. El ApplicationResponse indica 'firma inválida' sin especificar si el problema es el algoritmo, el certificado o la integridad del documento.

Certificado vencido: el NotAfter del certificado es anterior a la fecha de generación del documento. Diagnóstico: verificar programaticamente el NotAfter antes de firmar. Solución: renovar el certificado con la CA; no hay workaround posible.

XML modificado después de firmar: el pipeline de procesamiento modifica el XML entre la firma y el envío (serializa, reformatea, agrega declaración XML). El digest calculado ya no corresponde al documento transmitido. Solución: tratar el XML como bytes opacos desde el momento de la firma hasta el envío al OASF, sin ninguna transformación.

Algoritmo de canonicalización incorrecto: la DIAN espera Canonical XML 1.0 (Inclusive). Usar el algoritmo Exclusive produce un digest diferente. Verificar que la biblioteca de firma use el URI http://www.w3.org/TR/2001/REC-xml-c14n-20010315.

Categoría 4: errores de la capa OASF (no de la DIAN)

No todos los errores provienen de la validación DIAN. Algunos son propios del OASF y se distinguen por aparecer antes de que el documento llegue a la entidad fiscal. Identificarlos correctamente evita buscar el problema en el XML cuando en realidad está en la capa de transporte.

HTTP 401 Unauthorized: el token OAuth del OASF expiró. El integrador debe implementar renovación automática del token usando el refresh_token o repitiendo el flujo de autenticación. Nunca hardcodear tokens con fecha de expiración fija.

HTTP 429 Too Many Requests: el integrador superó el rate limit del OASF. Implementar backoff exponencial con jitter para envíos masivos. Consultar con el OASF el límite de documentos por minuto antes de ir a producción con cargas altas.

HTTP 504 Gateway Timeout: el OASF no recibió respuesta de la DIAN en el tiempo esperado. El documento puede estar en proceso. No marcar como fallido sin verificar el estado por CUNE. Implementar consulta diferida antes de reintentar el envío.

Estrategia de manejo de errores para integraciones en producción

Un sistema de nómina en producción necesita una estrategia de manejo de errores que distinga entre errores recuperables y errores definitivos. Los errores definitivos son los de esquema y regla de negocio — reintentar no sirve, el XML debe corregirse. Los errores recuperables son los transientes (timeout, rate limit, OASF en mantenimiento) — reintentar con el mismo XML puede funcionar.

# Pseudocódigo: clasificación de errores de nómina DIAN
def handle_oasf_response(response, document_id):
    """
    Clasifica la respuesta del OASF y decide la acción.
    """
    if response.http_status == 401:
        # Token expirado — recuperable
        refresh_auth_token()
        return Action.RETRY_IMMEDIATELY
    
    if response.http_status == 429:
        # Rate limit — recuperable con delay
        return Action.RETRY_WITH_BACKOFF
    
    if response.http_status in [502, 503, 504]:
        # OASF o DIAN no disponible — recuperable, verificar estado primero
        dian_status = check_document_status(document_id)
        if dian_status == 'APROBADO':
            return Action.MARK_APPROVED
        return Action.RETRY_WITH_BACKOFF
    
    if response.dian_code == '0':
        # Aprobado por la DIAN
        return Action.MARK_APPROVED
    
    if response.dian_code in SCHEMA_ERROR_CODES:
        # Error de esquema — definitivo, requiere corrección del XML
        log_error(f'Schema error: {response.dian_description}')
        return Action.MARK_FAILED_NEEDS_CORRECTION
    
    if response.dian_code in BUSINESS_RULE_CODES:
        # Error de regla de negocio — definitivo
        log_error(f'Business rule error: {response.dian_description}')
        return Action.MARK_FAILED_NEEDS_CORRECTION
    
    # Error desconocido — escalar para revisión manual
    return Action.ESCALATE

Preguntas frecuentes sobre errores en nómina electrónica DIAN

¿Cuál es el error más frecuente en la primera semana de integración de nómina electrónica?

El error más frecuente en la primera semana es el CUNE incorrecto, seguido de errores de firma por modificación del XML después de firmar. Ambos tienen la misma razón de fondo: el pipeline de generación aplica transformaciones (formateo de valores, serialización del XML) que deben ocurrir antes del cálculo del CUNE y antes de la firma, no después.

¿Cómo puedo saber si el error es de la DIAN o del OASF?

Los errores del OASF tienen códigos HTTP en la capa de transporte (401, 429, 503) sin ApplicationResponse de la DIAN adjunta. Los errores de la DIAN llegan dentro del ApplicationResponse XML, con códigos de error específicos en el elemento cbc:Note. Si el OASF retorna un error HTTP sin ApplicationResponse, el problema está entre el integrador y el OASF. Si retorna ApplicationResponse con estado rechazado, el problema está en el documento.

¿Qué diferencia hay entre un documento 'rechazado' y uno 'en proceso' en la respuesta del OASF?

Un documento rechazado tiene una ApplicationResponse de la DIAN con código de error específico — el rechazo es definitivo y el documento debe corregirse. Un documento 'en proceso' significa que el OASF lo recibió pero aún no recibió respuesta de la DIAN (la validación puede tardar). En este caso no hay ApplicationResponse definitiva aún — el integrador debe consultar el estado por ID de transacción o CUNE hasta recibir la respuesta final.

¿Es posible corregir un documento rechazado sin emitir una NANE?

Sí — si el documento fue rechazado por la DIAN, el rechazo significa que nunca fue aceptado. Un documento rechazado no existe en el sistema DIAN, por lo que puede corregirse y enviarse nuevamente como una NIDD nueva con un CUNE diferente. La NANE solo se requiere para corregir o anular documentos que ya fueron aceptados por la DIAN. Usar una NANE para 'corregir' un documento rechazado es un error conceptual que genera documentos innecesarios.

Sobre el autor

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.