Codis d'error de KSeF: què rebutja realment el sistema i com solucionar-ho

Una factura rebutjada no existeix. Legalment, no ha passat mai. No es pot corregir, anul·lar ni referenciar a la JPK_V7. Es corregeix l'error i es reenvia. Aquesta distinció sembla trivial fins que apareix un codi d'excepció 21401 un divendres a les 16:55 amb un client que espera el cobrament.

L'enquesta de Grant Thornton de l'abril de 2026 va revelar que el 74 per cent de les empreses va patir errors de facturació electrònica el primer mes de KSeF obligatori. El vint per cent va afirmar que aquells errors pertorbaven l'operativa diària. El problema no és teòric. És l'experiència més comuna després del llançament a l'ecosistema polonès de facturació.

Aquest article vincula cada codi de rebuig de la taxonomia de KSeF 2.0 amb la causa, el camp que falla i la solució exacta. També nomena els codis inventats que circulen en articles de granges de contingut, perquè actuar sobre una taxonomia falsa fa perdre temps i retrasa el reenviament.

KSeF només rebutja per dos motius

El Ministeri d'Hisenda va confirmar públicament el maig de 2026 que KSeF només valida dues coses: el compliment de l'esquema FA(3) i els permisos de l'emissor. No comprova el càlcul de l'IVA. No contrasta les dades del comprador amb el registre fiscal. No valida el valor del tipus de canvi. No confronta els imports de la factura amb cap base de dades externa.

Una factura conforme a l'esquema amb el tipus d'IVA incorrecte, el NIP del comprador incorrecte i un tipus de canvi inventat superarà la validació de KSeF i rebrà un número KSeF. L'Estat assigna el número, emet l'UPO (potwierdzenie przyjęcia, la confirmació de recepció) i la factura entra en circulació legal. L'error material surt a la llum setmanes després: a la conciliació, en una inspecció o quan el comprador descobreix que no pot deduir l'IVA suportat perquè la factura porta el NIP d'una altra persona.

No és un defecte de disseny. És l'arquitectura. KSeF és un sistema de compensació, no un sistema de validació. La validació material és responsabilitat del contribuent, és a dir, una llista de comprovació manual o una funció de producte. Plandesk incorpora una validació prèvia a l'enviament que comprova el que KSeF no comprova: dígit de control i consulta de registre del NIP, aritmètica de l'IVA, números de factura duplicats, verificació del tipus NBP i coherència dels codis GTU.

Estats de sessió: quan existeix de debò la vostra factura

Abans de desxifrar els codis de rebuig, cal entendre els estats de sessió. L'error més perjudicial després del llançament no és un rebuig. És un duplicat causat per reenviar durant el processament.

Els estats 100 i 150 no són errors. Signifiquen que KSeF ha rebut la factura i l'està processant. El temps de processament del Ministeri varia de segons a hores sota càrrega. Reenviar en aquesta finestra crea una factura duplicada amb un altre número KSeF, la causa més comuna de rebuigs amb codi 440.

Si useu una eina que consulta l'estat automàticament, deixeu-la treballar. Si useu l'Aplikacja Podatnika manualment, actualitzeu la pàgina d'estat de la sessió. No torneu a prémer "enviar".

La taxonomia real de codis d'error

KSeF 2.0 retorna un estat HTTP més un exceptionCode al cos de la resposta. Els codis següents provenen de la documentació oficial OpenAPI del Ministeri d'Hisenda. Són els codis amb què es troben els professionals.

Codi 21401: incompliment de l'esquema FA(3)

Què significa: L'XML enviat no s'ajusta a l'esquema FA(3).

Causes habituals:

• Plantilla FA(2) obsoleta encara en ús (FA(2) es va desactivar definitivament l'1 de febrer de 2026)
• Bytes BOM (marca d'ordre de bytes) a l'inici de l'arxiu XML
• Ordre incorrecte d'elements o elements obligatoris absents
• Declaració d'espai de noms incorrecta

Solució: Regenereu la factura des d'una plantilla FA(3) actual. Si useu programari de facturació, actualitzeu-lo a la darrera versió. No editeu mai l'XML a mà. L'esquema és tan estricte que les edicions manuals introdueixen més errors dels que corregeixen.

Exemple: La factura d'una autònoma es rebutja amb 21401 perquè l'eina de facturació es va actualitzar per darrera vegada el gener de 2026 i continua generant XML FA(2). La solució és actualitzar el programari, no editar l'XML.

Codi 21405: error de validació d'entrada

Què significa: Ha fallat una validació a nivell de camp. L'XML és estructuralment vàlid, però un camp concret conté dades en format incorrecte.

Causes habituals:

• NIP amb guions, espais o prefix "PL" (FA(3) espera 10 dígits sense separadors)
• Data en format incorrecte (FA(3) exigeix YYYY-MM-DD)
• Camp numèric amb coma decimal en lloc de punt
• KursWaluty amb menys de 6 decimals

Solució: Corregiu les dades d'origen a la fitxa del client o al formulari de factura i reenvieu. La resposta d'error inclou la ruta del camp, que indica exactament quin element cal corregir.

Exemple: La factura d'un autònom es rebutja amb 21405 perquè la fitxa del client desa el NIP del comprador com "PL-123-456-78-90". FA(3) espera "1234567890". Corregir la fitxa, regenerar, reenviar.

Codi 21301: error d'autorització

Què significa: L'emissor no té permís per emetre factures per al NIP de la capçalera de la factura.

Causes habituals:

• Token caducat (la vigència dels tokens KSeF depèn del tipus de concessió)
• Token emès per a un NIP distint del de la factura
• L'administrador va concedir drets d'emissió, però la concessió encara no ha surtit efecte
• Ús d'un accés personal (Profil Zaufany) en lloc de token o certificat

Solució: Regenereu el token amb els permisos correctes per al NIP emissor. Si useu un accés personal, canvieu a autenticació per token. L'autenticació per token era el mètode recomanat abans del llançament i es va convertir en l'estàndard de facto després del col·lapse de Profil Zaufany els dies 2 i 3 de febrer de 2026.

Exemple: Una assessoria intenta emetre una factura per a un client nou i rep 21301. El token de l'assessoria es va emetre abans que el client s'afegís als seus permisos de KSeF. La solució: concedir drets d'emissió per al NIP del client i regenerar el token.

Codi 440: factura duplicada

Què significa: Ja existeix a KSeF una factura amb el mateix número del mateix emissor.

Causes habituals:

• Reenviament a cegues després d'un temps d'espera esgotat (la causa més comuna)
• Emissió en paral·lel a través de l'app de facturació i de l'Aplikacja Podatnika
• Estat de sessió no comprovat abans de reenviar

Solució: Consulteu KSeF amb el vostre propi número de factura abans de reenviar. Si el primer enviament ha tingut èxit (estat 200), adopteu la factura existent. No creeu un duplicat. Si el primer enviament ha fallat de veritat, corregiu l'error i reenvieu amb el mateix número de factura.

Exemple: Un usuari envia una factura, rep un temps d'espera esgotat i reenvia. El primer enviament en realitat va tenir èxit, només que la resposta va arribar tard. El segon enviament topa amb el 440. L'acció correcta: comprovar l'estat de la primera sessió, trobar el 200 i fer servir aquest número KSeF.

HTTP 500, 503, 429: errors del servidor

Què significa: La plataforma KSeF està sobrecarregada o limita la taxa de peticions.

Causes habituals:

• Onades de trànsit del període de llançament (febrer i abril de 2026)
• Limitació de taxa després de massa peticions en poc temps
• Problemes transitoris d'infraestructura

Solució: Implementar reintents amb espera progressiva. Si l'error persisteix, canviar al mode offline24: emetre la factura localment i transmetre-la abans del dia laborable següent. La data d'emissió P_1 es conserva en mode offline, de manera que la data legal de la factura no es desplaça.

Factures fantasma: acceptades però invisibles

Un patró que no genera codi de rebuig però fa mal igual: la factura s'accepta (estat 200, número KSeF assignat, UPO emès), però el comprador no la veu a la safata de KSeF. La deducció d'IVA queda bloquejada. Els experts ho atribueixen a fallades d'integració entre l'ERP i KSeF i a una semàntica poc clara dels estats enviada, acceptada i rebutjada.

La factura existeix. És en circulació legal. El comptable del comprador simplement no hi pot accedir. La solució temporal: el venedor comparteix el número KSeF i l'UPO directament amb el comprador, que pot consultar KSeF manualment. La solució estructural és una millor sincronització d'estats entre KSeF i els sistemes comptables comercials, un dels problemes que ha d'abordar el paquet de "7 millores" anunciat pel Ministeri per a l'1 de gener de 2027.

Codis d'error inventats que heu d'ignorar

Les granges de contingut han inventat codis d'error que no existeixen a la documentació de l'API de KSeF. Si busqueu codis d'error de KSeF, trobareu articles que esmenten codis com "TOTAL_MISMATCH", "NIP_REGISTRY_REJECTION" o "VAT_RATE_INVALID". Són inventats. No corresponen a cap exceptionCode de l'especificació OpenAPI oficial.

El Ministeri d'Hisenda ha declarat públicament que KSeF no valida aritmètica, dades del comprador ni tipus d'IVA. Tot article que afirmin que KSeF rebutja factures per imports d'IVA incorrectes o per NIP de comprador no registrats està equivocat. Aquests errors passen per KSeF. Surten a la llum després: com a correccions, inspeccions o deduccions d'IVA suportat perdudes.

Si us trobeu un codi d'error que no apareix a la documentació oficial, comproveu la font. La referència autoritzada és l'especificació OpenAPI publicada pel Ministeri d'Hisenda i reflectida al repositori de documentació de l'API de KSeF.

Set comprovacions abans de cada enviament

Executeu aquestes comprovacions abans d'enviar cap factura a KSeF. Atrapen els errors que KSeF no atrapa.

1. Format del NIP: 10 dígits, sense guions, sense espais, sense prefix "PL".
2. Dígit de control del NIP: Valideu el dígit de control. KSeF no el comprova.
3. Consulta del NIP al registre: Verifiqueu que el comprador figura a la biała lista podatników VAT (llista blanca de contribuents de l'IVA).
4. Aritmètica de l'IVA: Net per tipus igual a IVA. Net més IVA igual a brut. Comproveu cada línia.
5. Unicitat del número de factura: Consulteu KSeF amb el vostre propi número de factura abans d'enviar.
6. Coherència de dates: La data d'emissió (P_1) és avui o és dins de la finestra offline24. Gens de retrodatació.
7. Camps de divisa: KodWaluty és un codi ISO 4217 vàlid. KursWaluty té 6 decimals. El tipus coincideix amb la taula del NBP del dia correcte.

Aquestes comprovacions porten segons en programari i eliminen la majoria dels errors posteriors al llançament. Fer-les manualment és possible però propens a errors, per això la validació prèvia a l'enviament existeix com a funció de producte i no com a exercici de documentació.

Aquest material té caràcter informatiu general i no constitueix assessorament legal ni fiscal. Per a un cas concret, verifiqueu la normativa vigent o consulteu un assessor qualificat.