Error Codes in KSeF 2.0 – What Do They Mean and How Should You Respond Safely?

It is easy to treat error codes in KSeF as a purely technical issue and hand them over to the IT team or the ERP system provider. In practice, however, the messages returned by the National e-Invoicing System (KSeF) have much broader implications. They can affect the timeliness of invoice issuance, the accuracy of tax settlements, accounting processes, document workflow, and the allocation of organizational responsibility between finance, accounting, and IT.

Aider Poland

elegancka, zamyślona kobieta pracuje przy biurku

From the perspective of a CFO, chief accountant, or a person responsible for financial processes, KSeF error codes should not be viewed merely as a list of numbers to be passed on to an integration provider. An error code table may be helpful, but it does not solve the problem. With KSeF 2.0, what matters far more is determining at which stage of the process the error occurs, whether the invoice has already been successfully accepted into the system, whether it has received a KSeF number, and whether the issue is technical, configuration-related, accounting-related, or tax-related.


In practice, the exact same error code may require completely different actions on the organization’s side. Sometimes it is enough to retry communication with the system. In other cases, it may be necessary to correct data mapping in the ERP system, conduct a tax analysis, or issue a corrective invoice.


What are KSeF error codes?


KSeF error codes are messages returned by the system during the submission, retrieval, or processing of structured invoices. They may relate to:


  • authentication and authorization,
  • certificates and tokens,
  • permissions to operate within a specific context,
  • XML file validation,
  • interactive or batch session status,
  • API limits,
  • retrieval of documents and confirmation receipts (UPO),
  • technical infrastructure errors.

In practice, this means that not every KSeF error indicates an invoice error. Some messages relate solely to the integration layer and do not require any corrections to the document itself.

KSeF error codes vs. QR codes — they are not the same


In practice, the term “KSeF codes” is often used to describe two completely different topics.


The first refers to KSeF error codes — system messages returned by the KSeF API or the document validator. These inform users about issues such as authentication problems, token errors, session status, query limits, XML structure issues, or invoice retrieval failures.


The second refers to KSeF QR codes, which are placed on the visual representation of an invoice in cases defined by regulations and technical documentation — both when using an invoice outside KSeF after it has been submitted to the system, and in offline/offline24 or emergency modes. Their purpose is to enable verification of document data and provide access to the invoice within KSeF.


This distinction matters in practice. A QR code is not a KSeF error and does not indicate any issue with the document.

Księgowa z Optima

Does every KSeF error mean there is an invoice error?


One of the most common misconceptions is the assumption that if the system returns an error, the problem automatically concerns the invoice content. However, this is not necessarily the case. An error may result from:


  • an invalid technical request,
  • an authentication error,
  • an incorrect operating context,
  • insufficient permissions,
  • an expired token,
  • exceeding API limits,
  • an incorrect session status,
  • integration configuration issues,
  • or only then from the invoice XML file itself.

For this reason, when analyzing KSeF errors, it is worth looking at several response layers:


  • HTTP Status – the first technical signal indicating whether the system accepted the request.
  • ExceptionCode (KSeF error code) – the detailed cause of the problem.
  • Invoice process status – whether the document was successfully accepted into the system and assigned a KSeF number.

Only after making this distinction can you determine whether the issue should be handled by IT, accounting, tax specialists, or the system provider.


HTTP Status in KSeF – the first sign of a problem


The first communication layer with KSeF is the HTTP status. It indicates whether the request was processed correctly or whether there was an issue with authorization, API limits, or infrastructure.


400 – Invalid request


Most commonly indicates a problem with input data validation, an invalid request, or incorrect data structure.


What to check?


  • endpoint parameters
  • API response content
  • ExceptionCode
  • input data correctness
  • invoice XML file

401 – Authentication failure


Most commonly indicates a problem with the token, certificate, or authentication session.


What to check?


  • token validity
  • signature configuration
  • certificate
  • session activity

403 – Insufficient permissions


The user or system does not have sufficient rights to perform the operation.


What to check?


  • taxpayer identification (NIP) context
  • assigned permissions
  • permission type required for the specific operation

410 – Operation expired


Most commonly indicates that the availability period of a process or result has expired.


429 – API request limit exceeded


This is one of the most frequently misunderstood errors. It does not indicate an invoice error.


It simply means too many requests were made within a given period. In such cases, the solution is not to correct the invoice but to:


  • queue requests
  • implement retry logic
  • analyze the Retry-After header
  • optimize integration

500 / 5xx – KSeF server-side error


Most commonly indicates a technical issue on the infrastructure side.


What to do?


  • secure application logs
  • store the traceId
  • retry according to the retry procedure
  • monitor technical announcements from the Ministry of Finance

Does KSeF invoice acceptance mean the document is correct?


No. This is one of the most important practical issues.


Successful acceptance of an invoice by KSeF and assignment of a KSeF number does not automatically mean the document is substantively correct.


The system mainly verifies:


  • XML compliance with the logical structure
  • technical correctness of the file
  • schema compliance

KSeF does not verify, among other things:


  • VAT settlement correctness
  • legitimacy of the transaction
  • arithmetic correctness
  • business correctness of the document

In practice, this means an invoice may pass technical validation even if it contains accounting or tax errors.


If the document has already been accepted into the system and assigned a KSeF number, it cannot simply be deleted or corrected in the ERP system. In such cases, it is necessary to determine whether a corrective invoice must be issued or, in specific situations, whether a technical correction may be applied.


Key KSeF 2.0 Error Codes and Statuses – Practical Overview


The table below provides a practical overview of the most important KSeF error codes, their meaning, and recommended organizational responses.


Code / Status Response Layer Practical Meaning Recommended Action
400 HTTP Status Invalid request or input validation error Review API response, ExceptionCode, endpoint parameters, input data, and XML
401 HTTP Status Authentication failure Verify token, certificate, authentication session
403 HTTP Status Insufficient permissions Check KSeF permissions, NIP context
410 HTTP Status Operation expired Determine whether the process or result availability has expired
429 HTTP Status API rate limit exceeded Check Retry-After, queue requests, optimize integration
500 / 5xx HTTP Status Infrastructure/service error Save logs and traceId, retry, monitor system communications
21111 ExceptionCode Invalid authentication challenge Verify challenge, encryption method, timestamp
21115 ExceptionCode Invalid certificate Validate certificate and its expiry
21117 ExceptionCode Invalid entity identifier for context Check NIP or entity identifier
21155 ExceptionCode Invoice session limit exceeded Close current session or open a new one
21157 ExceptionCode Invalid package part size Check batch package sizes
21161 ExceptionCode Package part limit exceeded Verify batch package configuration
21164 ExceptionCode Invoice does not exist Verify KSeF number and access context
21165 ExceptionCode Invoice not yet available Wait and retry retrieval
21166 ExceptionCode Technical correction unavailable Verify correction eligibility
21167 ExceptionCode Invoice status blocks correction Check invoice status
21173 ExceptionCode Session not found Verify session reference
21175 ExceptionCode Query result not found Verify query/export reference
21178 ExceptionCode UPO not found Check session/invoice status
21180 ExceptionCode Session status blocks operation Verify session state
21181 ExceptionCode Invalid export request Review export criteria
21182 ExceptionCode Export limit reached Reduce concurrent exports
21183 ExceptionCode Filter range exceeds limits Verify date ranges and filters
21205 ExceptionCode Package cannot be empty Ensure all batch parts were uploaded
21208 ExceptionCode Upload/finish timeout exceeded Retry batch process
21217 ExceptionCode Invalid character encoding Verify document encoding
21301 ExceptionCode Authorization missing Verify authentication status and token
21304 ExceptionCode Authentication missing Verify authentication operation
21308 ExceptionCode Authentication method belongs to deceased person Special authorization issue requiring investigation
21401 ExceptionCode Document not compliant with XSD schema Validate XML against schema
21402 ExceptionCode Invalid file size Verify declared vs actual file size
21403 ExceptionCode Invalid file hash Verify hashing method
21405 ExceptionCode Input validation error Analyze detailed validator message
21406 ExceptionCode Signature/authentication conflict Verify signature type and auth method
21418 ExceptionCode Invalid continuation token format Verify pagination token
21470 ExceptionCode Unknown or retired key ID Verify publicKeyId
25001 ExceptionCode Cannot retrieve CSR data Verify auth method and permissions
25002 ExceptionCode Certification request cannot be submitted Verify certification eligibility
25003 ExceptionCode CSR data mismatch Compare CSR and authentication data
25004 ExceptionCode Invalid CSR format/signature Validate CSR structure and signature
25005 ExceptionCode Certification request not found Verify reference number
25006 ExceptionCode Certification request limit reached Review certificate request limits
25007 ExceptionCode Certificate limit reached Review active certificates
25010 ExceptionCode Invalid key type or length Verify key parameters
25011 ExceptionCode Invalid CSR signing algorithm Verify signature algorithm
26001 ExceptionCode Cannot grant unavailable permissions to token Check actual permissions
26002 ExceptionCode Token cannot be generated in current context Verify context
9101 ExceptionCode Invalid document Verify document used for signing/authentication
9102 ExceptionCode Missing signature Ensure signature is attached
9103 ExceptionCode Too many signatures Verify signature count


This overview is based on the official KSeF 2.0 API documentation, OpenAPI specifications, and technical materials published by the Polish Ministry of Finance. It is intended as a practical aid and should not replace ongoing verification of current technical documentation.

Why Is a Simple List of KSeF Error Codes Not Enough?


A table of error codes can certainly be useful, especially during the initial diagnosis of a problem. It helps quickly determine whether a message relates to authorization, permissions, API limits, sessions, tokens, certificates, invoice retrieval, or the invoice XML file itself.


However, it should not be treated as a complete troubleshooting guide. In practice, the following also matters:


  • HTTP status
  • API response content
  • invoice status
  • process stage
  • reference number
  • traceId
  • environment (test vs. production)

The exact same error code may require different actions depending on the business context.

profil-zaufany-czy-ulatwia-zalatwianie-spraw-ksiegowych-w-firmie

How Should KSeF Errors Be Handled in Practice?


The safest approach is a process-based approach. For every significant error, it is worth capturing:


  • HTTP status
  • full error message
  • ExceptionCode
  • traceId
  • operation reference number
  • invoice status
  • KSeF number (if already assigned)

Having this information significantly speeds up analysis and reduces organizational confusion between accounting, IT, and the software provider.


KSeF Error Codes and Internal Procedures


With mandatory KSeF, error handling should become part of an organization’s internal procedures.


In practice, it is worth separating at least the following categories:


  • technical errors
  • authentication errors
  • XML and validation errors
  • errors occurring after invoice acceptance in KSeF
  • issues related to QR codes and invoice visualization

Each of these situations requires a different response.


Sometimes simply retrying communication with the system is sufficient. In other cases, data in the source system must be corrected. In more complex scenarios, tax analysis or intervention from the software provider may be necessary.

FAQ

Most Frequently Asked Questions About KSeF Errors