How to read KSeF error codes without guessing?

KSeF (Poland's national e-invoicing system) answers with a number and one sentence, and within the same minute someone has to choose between three very different actions: fix the XML, retry the request, or hand the case to accounting. Three decisions, three costs, three deadlines.

The penalty-free transition period ends on 31 December 2026. From 1 January 2027, an invoice that never reached the system stops being a technical problem and becomes a financial one. If you run a Polish entity or a Polish subsidiary, the thing worth building before then is a procedure for reading gateway messages — not a habit of pasting codes into a search box.

This is the map: how a KSeF response is structured, what each code family covers, which codes are safe to simply retry, and where the handover from engineering to accounting actually sits. The full catalogue — 133 messages with plain-language meaning and a recommended action — lives in the KSeF Error Dictionary.

A KSeF message has three layers, not one

An error number without context is useless. The same 21405 can mean a malformed query parameter one day and a badly mapped ERP field the next. Read every response on three levels:

1. HTTP status — whether the gateway accepted the request at all.

2. exceptionCode and exceptionDescription — the specific reason on the KSeF side.

3. Invoice or session status — whether the document already carries a KSeF number, or does not exist in the system yet.

Only together do these say whose problem it is. Layers one and two belong to the integration. Layer three belongs to accounting, because that is where the decision about a correcting invoice is made.

Two identifiers deserve to be logged every single time: the operation's referenceNumber and the response's traceId. Without them, a ticket to the Ministry of Finance or to your software vendor is an anecdote rather than a report.

Code families: what the leading digits tell you

KSeF 2.0 numbering is not arbitrary. The leading digits point at the subsystem that rejected the request — enough to route the case to the right person in seconds.

Family Area Who fixes it 9xxx signature and authorisation document integrator 211xx authentication, sessions, invoice retrieval, export integrator 212xx batch package and its parts integrator 213xx authorisation and access tokens company administrator 214xx document and input-data validation integrator or invoice issuer 250xx KSeF certificates company administrator 260xx KSeF tokens company administrator

Rule of thumb: anything below 214xx is usually configuration, not the invoice. Editing a document in response to an authentication error is the most common way to lose an hour.

HTTP statuses: the first branch

Status Meaning Response 400 malformed request or input-data validation failure read exceptionCode and the errors list in the payload 401 authentication missing or invalid token, certificate, session validity 403 insufficient permissions or disallowed context NIP (Polish tax ID) context and the permission scope for that operation 410 the operation has expired and is no longer available start the process again 415 operation type not allowed in this submission mode switch modes (see the case below) 429 API rate limit exceeded Retry-After, queueing, backoff — do not touch the invoice 5xx failure on the KSeF infrastructure side capture traceId, retry per your retry policy

The most expensive misreading in this table is 429. Under real API limits it is easy to treat it as a document rejection and start "fixing" a perfectly valid invoice. Current limits are published in the CIRF/MF documentation.

The most frequent codes and what they mean

Signature and authorisation document (9xxx)

Code Message Action 9101 Invalid document check the document used in the signing process 9102 Signature missing the required signature was not attached 9103 Too many signatures verify the signature count for this document type

Sessions, invoices and export (211xx)

Code Message Action 21111 Invalid authorisation challenge challenge, encryption and timing in the auth flow 21115 Invalid certificate validity and compliance with KSeF requirements 21117 Invalid subject identifier for the context type the NIP does not match the selected context type 21155 Invoice limit for the session exceeded close the session and open a new one 21157 Invalid package part size declared part size ≠ actual file 21161 Too many package parts rebuild the batch package 21164 Invoice with the given identifier does not exist KSeF number, subject context, retrieval permissions 21165 Invoice not available yet not an error — wait and poll again 21166 Technical correction unavailable it has most likely already been processed 21167 Invoice status does not allow a technical correction an accounting case, not an integration one 21173 No session with that reference number reference number or environment (test vs. production) 21175 Query result does not exist export reference, or the result's availability window expired 21178 No UPO found for the given criteria the UPO (official receipt confirmation) is issued after the session closes — retry later 21180 Session status does not allow the operation session closed or cancelled 21181 Invalid invoice export request export criteria and subject context 21182 Concurrent export limit reached reduce parallel exports 21183 Filter range outside the available data range date range and date type

Batch package (212xx)

Code Message Action 21205 Package must not be empty not all declared parts were uploaded 21208 Upload or finish timeout exceeded the session may have been cancelled — repeat the process 21217 Invalid character encoding UTF-8, no BOM

Authentication and authorisation (213xx)

Code Message Action 21301 Not authorised token revoked, or the authentication operation never completed 21304 Not authenticated no operation with that reference number in this environment 21308 Attempt to use the authorisation methods of a deceased person the entity's authentication path has to change

Document and input validation (214xx)

Code Message Action 21401 Document does not conform to the XSD schema the classic "invoice error": FA(3) structure, mandatory fields, encoding 21402 Invalid file size declared size ≠ actual content length 21403 Invalid file hash how the hash is computed 21405 Input-data validation error read the details, not the number — the code alone says nothing 21406 Signature and authentication type conflict auth method vs. certificate type 21418 Invalid continuation token format never edit the pagination token by hand 21470 Unknown or withdrawn key identifier fetch the current public key for your environment

Certificates and tokens (250xx, 260xx)

Code Message Action 25001 CSR data cannot be retrieved for this authentication method change the authentication method 25002 Certificate request cannot be submitted for this method as above 25003 CSR data does not match the authentication vector subject data inside the CSR 25004 Invalid CSR format or signature request format and signing algorithm 25005 Certificate request with that reference number does not exist reference number and environment 25006 Certificate request limit reached clean up outstanding requests 25007 Held-certificate limit reached revoke unused certificates 25010 Invalid key type or length key requirements in the certificate docs 25011 Invalid CSR signing algorithm algorithm and hash function 26001 Cannot grant a token permissions the subject does not hold fix the subject's permissions first 26002 Cannot issue a token for the current context type tokens are issued only in permitted contexts

The KSeF 2.0 catalogue is larger than the list above. All 133 entries, mapped against the OpenAPI contract, sit in the KSeF Error Dictionary; the source of truth remains the API documentation at api.ksef.mf.gov.pl and the CIRF/MF integrator guide.

Same document, two different answers: a case from our own rollout

On 10 September 2026, on the Ministry's test environment, we were testing invoices with attachments. The same invoice submitted through an interactive session came back with HTTP 415 and a message stating that an invoice with an attachment cannot be sent that way. The same invoice in a batch session was accepted. And the same interactive session accepted the same invoice once the attachment node was removed.

The uncomfortable but useful conclusion: some messages do not say "this document is wrong" — they say "not through this channel". Anyone who had started by editing the XML would have been editing a valid file. The differences between modes are documented in the batch session guide.

An error does not always mean the invoice is missing

The costliest mistakes happen on the other side of the line: when the invoice already has a KSeF number.

Acceptance by the gateway means conformity with the logical structure, and nothing more. KSeF does not check VAT treatment, commercial substance, or arithmetic. An invoice with the wrong rate can pass technical validation without a single message.

The practical consequence: a document that received a KSeF number cannot be withdrawn or overwritten from your sales system. What remains is a correcting invoice or — in the narrow set of cases the regulations allow — a technical correction. That is an accounting decision, not an integration one, which is exactly why the third layer of the message must never be skipped.

Duplicates are a separate trap. KSeF identifies them from a combination of seller data, invoice type and document number, and keeps uniqueness for years — resending "just in case" is not a neutral act.

Checklist: what to capture for every error

1. HTTP status of the response.

2. exceptionCode and the full exceptionDescription.

3. referenceNumber of the operation (session, request, export).

4. traceId from the response.

5. Environment: test or production.

6. Invoice status: was a KSeF number assigned.

7. UTC timestamp — with rate limits and sessions, the second matters.

Those seven fields turn "it doesn't work on our side" into something that can actually be investigated. Reporting paths are described on the integrator support page.

Summary

KSeF error codes look like a purely technical topic, yet they settle accounting questions: whether the invoice exists, whether the deadline was met, whether a correction is required. Three layers of the response, the family map and seven checklist fields are enough to stop guessing.

Biurko translates gateway messages into one plain sentence and one suggested action, and retries after 429 and 5xx happen without your involvement. Start a 14-day free trial at biurko.io and see what submitting to KSeF looks like when nobody has to read numbers.

FAQ

What does KSeF error 21401 mean? The document does not conform to the XSD schema. In practice it usually comes down to the FA(3) structure, an empty mandatory field, or encoding other than UTF-8 without BOM. The number itself does not identify the field — the validator message returned alongside it does.

Does a 429 error mean my invoice was rejected? No. It signals that the API rate limit was exceeded and concerns the integration only. The invoice is fine. The fix is reading the Retry-After header, queueing requests and applying exponential backoff — not editing the document.

If KSeF accepts an invoice, is the invoice correct? No. The system validates conformity with the logical structure and the technical soundness of the file. It does not verify VAT settlement or arithmetic. An invoice with a substantive error can receive a KSeF number and need a correction later.

Where is the official list of KSeF error codes? The source of truth is the OpenAPI contract and the API 2.0 documentation on api.ksef.mf.gov.pl, together with the CIRF/MF repository holding the integrator guide and the changelog, where the Ministry publishes newly added codes.

What if an invoice already has a KSeF number but contains an error? It cannot be deleted or overwritten. The standard route is a correcting invoice; a technical correction is available only in cases foreseen by the regulations and only for specific document statuses.