Reading KSeF Errors in Plain Language: Code, Cause, Field, Fix

KSeF error messages are the number-one UX complaint in the post-launch market. The system returns numeric exception codes (21401, 21405, 21301, 440) with developer-grade descriptions like "Dokument nie jest zgodny ze schemą XSD." No Polish vendor ships a plain-language explanation. The codes are deterministic, which makes them ideal for citation-grounded translation: each code maps to one cause, one failing field, and one fix.

The Decoder

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

Plain language: Your invoice XML does not match the FA(3) schema. The structure is wrong.

Cause: The XML was generated from an outdated template (FA(2) instead of FA(3)), contains invalid characters (BOM bytes), has elements in the wrong order, or is missing mandatory elements.

Failing field: The error response includes the XPath to the failing element. Look for the field path in the response.

Fix: Regenerate the invoice from a current FA(3) template. Update your invoicing software to the latest version. Do not hand-edit XML.

21405: Input validation error

Plain language: A specific field contains data in the wrong format. The XML structure is correct, but one field's content fails validation.

Cause: NIP with dashes or spaces, date in the wrong format, numeric field with a comma instead of a dot, or KursWaluty with fewer than 6 decimal places.

Failing field: The error response names the specific field. Common culprits: NIP (buyer or seller), P_1 (issue date), KursWaluty.

Fix: Correct the source data in your contractor card or invoice form. For NIP: remove all dashes, spaces, and "PL" prefixes. For dates: use YYYY-MM-DD. For decimals: use dot, not comma. Resend.

21301: "brak autoryzacji"

Plain language: You do not have permission to issue invoices for the NIP in the invoice header.

Cause: Your token expired, was issued for a different NIP, or your permissions do not include issuing rights for this entity.

Failing field: NIP in the invoice header vs. NIP on the token.

Fix: Regenerate the token with the correct scopes for the issuing NIP. If using a personal login (Profil Zaufany), switch to token-based authentication. If you are an accounting office, verify that the client granted you issuing rights for their NIP.

440: Duplicate

Plain language: An invoice with the same number from the same issuer already exists in KSeF.

Cause: You resent an invoice that was already submitted successfully. The first submission succeeded but you did not check the status before resending.

Failing field: Invoice number (NrFaktury).

Fix: Query KSeF by your own invoice number. If the first submission succeeded (status 200), use the existing KSeF number. Do not create a duplicate. If the first submission genuinely failed, fix the error and resend with the same invoice number.

Status 100 or 150: Not an error

Plain language: Your invoice is being processed. Wait.

Cause: KSeF received the invoice and is processing it. Processing time varies from seconds to hours under load.

Fix: Poll the same session. Do not resend. Resending creates a duplicate.

HTTP 500, 503, 429: Server error

Plain language: KSeF is overloaded or rate-limiting you.

Cause: Launch-period traffic, transient infrastructure issues, or too many requests in a short window.

Fix: Retry with backoff. If the error persists, switch to offline24 mode. Issue the invoice locally and submit by the next working day.

Why No Vendor Ships This

The error codes are deterministic. They map to fixed causes and fixes. An explanation engine is technically straightforward: a lookup table from code to cause-field-fix, with citations to the official documentation.

No Polish vendor ships it because the incumbents were built before KSeF and treat error handling as an afterthought. Their error messages are raw API responses wrapped in a thin UI. The user sees "21401" and has to search the web for an explanation, where they find content-farm articles with fabricated codes.

The opportunity is to ship the explanation engine as a free, genuinely useful tool. Every error code in the real taxonomy, mapped to plain language, with citations to the official OpenAPI documentation. No fabricated codes. No invented procedures. The user searches for "błąd 21401 KSeF" and finds a page that says: "Your XML does not match the FA(3) schema. Here is why. Here is the field to fix. Here is how to fix it."

That page ranks. It ranks because it is accurate, sourced, and useful. It ranks because every content-farm alternative is wrong. The accuracy is the moat.

AI Act Compliance

If the explanation engine uses AI (e.g., a language model to generate the plain-language text from the code and context), AI Act Article 50 requires disclosure that the user is interacting with an AI system and machine-readable marking of AI-generated content. From 2 August 2026, this is mandatory.

The safer design: a deterministic lookup table, not a language model. The codes are fixed. The causes are fixed. The fixes are fixed. A lookup table is more accurate, faster, and exempt from AI Act transparency duties. Use AI for the things that benefit from reasoning (parameter suggestions, drafting). Use a lookup table for the things that are deterministic (error codes).

This material is information of a general nature and does not constitute legal or tax advice. For a specific situation, verify the current rules or consult a qualified adviser.