Leer los errores de KSeF en lenguaje claro: código, causa, campo, solución

Los mensajes de error de KSeF son la primera queja de UX del mercado tras el lanzamiento. El sistema devuelve códigos numéricos de excepción (21401, 21405, 21301, 440) con descripciones de nivel desarrollador como "Dokument nie jest zgodny ze schemą XSD". Ningún proveedor polaco ofrece una explicación en lenguaje claro. Los códigos son deterministas, lo que los hace ideales para una traducción fundamentada en citas: cada código mapea a una causa, un campo fallido y una solución.

El decodificador

21401: "Dokument nie jest zgodny ze schemą XSD"

Lenguaje claro: Su XML de factura no coincide con el esquema FA(3). La estructura es incorrecta.

Causa: El XML se generó desde una plantilla obsoleta (FA(2) en lugar de FA(3)), contiene caracteres no válidos (bytes BOM), tiene elementos en orden incorrecto o le faltan elementos obligatorios.

Campo fallido: La respuesta de error incluye el XPath del elemento fallido. Busque la ruta del campo en la respuesta.

Solución: Regenere la factura desde una plantilla FA(3) actual. Actualice su software de facturación a la última versión. No edite el XML a mano.

21405: Error de validación de entrada

Lenguaje claro: Un campo concreto contiene datos en formato incorrecto. La estructura del XML es correcta, pero el contenido de un campo no supera la validación.

Causa: NIP con guiones o espacios, fecha en formato incorrecto, campo numérico con coma en lugar de punto, o KursWaluty con menos de 6 decimales.

Campo fallido: La respuesta de error nombra el campo concreto. Sospechosos habituales: NIP (comprador o vendedor), P_1 (fecha de emisión), KursWaluty.

Solución: Corrija los datos de origen en la ficha del cliente o en el formulario de factura. Para el NIP: quite todos los guiones, espacios y prefijos "PL". Para las fechas: use AAAA-MM-DD. Para los decimales: use punto, no coma. Reenvíe.

21301: "brak autoryzacji"

Lenguaje claro: No tiene permiso para emitir facturas para el NIP de la cabecera de la factura.

Causa: Su token caducó, se emitió para un NIP distinto o sus permisos no incluyen derechos de emisión para esta entidad.

Campo fallido: NIP de la cabecera de la factura frente a NIP del token.

Solución: Regenere el token con los alcances correctos para el NIP emisor. Si usa un inicio de sesión personal (Profil Zaufany), cambie a autenticación por token. Si es una asesoría, verifique que el cliente le concedió derechos de emisión sobre su NIP.

440: Duplicado

Lenguaje claro: Ya existe en KSeF una factura con el mismo número del mismo emisor.

Causa: Reenvió una factura que ya se había enviado con éxito. El primer envío funcionó pero usted no comprobó el estado antes de reenviar.

Campo fallido: Número de factura (NrFaktury).

Solución: Consulte KSeF por su propio número de factura. Si el primer envío tuvo éxito (estado 200), use el número KSeF existente. No cree un duplicado. Si el primer envío falló de verdad, corrija el error y reenvíe con el mismo número de factura.

Estado 100 o 150: No es un error

Lenguaje claro: Su factura se está procesando. Espere.

Causa: KSeF recibió la factura y la está procesando. El tiempo de procesamiento varía de segundos a horas bajo carga.

Solución: Consulte la misma sesión. No reenvíe. Reenviar crea un duplicado.

HTTP 500, 503, 429: Error del servidor

Lenguaje claro: KSeF está sobrecargado o le está limitando la tasa de peticiones.

Causa: Tráfico del período de lanzamiento, problemas transitorios de infraestructura o demasiadas peticiones en una ventana corta.

Solución: Reintente con espera progresiva. Si el error persiste, cambie al modo offline24. Emita la factura localmente y envíela antes del siguiente día laborable.

Por qué ningún proveedor lo ofrece

Los códigos de error son deterministas. Mapean a causas y soluciones fijas. Un motor de explicación es técnicamente sencillo: una tabla de correspondencia de código a causa-campo-solución, con citas de la documentación oficial.

Ningún proveedor polaco lo ofrece porque los productos establecidos se construyeron antes de KSeF y tratan la gestión de errores como algo secundario. Sus mensajes de error son respuestas crudas de la API envueltas en una capa fina de interfaz. El usuario ve "21401" y tiene que buscar una explicación en internet, donde encuentra artículos de granjas de contenidos con códigos inventados.

La oportunidad es ofrecer el motor de explicación como una herramienta gratuita y realmente útil. Cada código de error de la taxonomía real, mapeado a lenguaje claro, con citas de la documentación OpenAPI oficial. Sin códigos inventados. Sin procedimientos fabricados. El usuario busca "błąd 21401 KSeF" y encuentra una página que dice: "Su XML no coincide con el esquema FA(3). Este es el motivo. Este es el campo a corregir. Así se corrige."

Esa página posiciona. Posiciona porque es precisa, tiene fuentes y es útil. Posiciona porque cada alternativa de granja de contenidos es incorrecta. La precisión es el foso defensivo.

Cumplimiento del Reglamento de IA

Si el motor de explicación usa IA (por ejemplo, un modelo de lenguaje para generar el texto en lenguaje claro a partir del código y el contexto), el artículo 50 del Reglamento de IA exige revelar que el usuario interactúa con un sistema de IA y el marcado legible por máquina del contenido generado por IA. Desde el 2 de agosto de 2026, es obligatorio.

El diseño más seguro: una tabla de correspondencia determinista, no un modelo de lenguaje. Los códigos son fijos. Las causas son fijas. Las soluciones son fijas. Una tabla de correspondencia es más precisa, más rápida y está exenta de las obligaciones de transparencia del Reglamento de IA. Use IA para lo que se beneficia del razonamiento (sugerencias de parámetros, redacción). Use una tabla de correspondencia para lo que es determinista (códigos de error).

Este material es información de carácter general y no constituye asesoramiento legal ni fiscal. Para una situación concreta, verifique la normativa vigente o consulte a un asesor cualificado.