KSeF API error codes: what each one means and what to tell your users
Gideon Awolesi ·
If your product sends invoices to Poland's KSeF, sooner or later it'll get an error back. The Ministry of Finance doesn't publish one complete list of these codes. They're spread across the API specification, endpoint by endpoint. We built InvoiceRate on the KSeF API, so we've had to deal with them in a real product. This page collects the most common codes from the official specification, explains what each one means in plain English, and suggests what to show the person using your product.
01KSeF returns two different kinds of code
This trips a lot of teams up. When a request fails straight away, the API returns an HTTP error with a 4 or 5-digit exceptionCode. But sending an invoice is asynchronous, so a successful request only means KSeF accepted it for processing. You then poll the invoice's status, and that returns a 3-digit status code.
The 3-digit status codes look like HTTP statuses, but they aren't. The same number can mean different things on different resources. For example, status 415 on an authentication means the user has no permissions, while status 415 on an invoice means attachments aren't allowed for that taxpayer.
You can also ask for errors in the Problem Details format by sending the header X-Error-Format: problem-details. The older JSON format still works, though the specification marks it as deprecated.
02Invoice status codes
These come back when you check the status of a single invoice in a session. They're the codes your users care about most, because they decide if the invoice was issued.
| Code | Official name (Polish) | What it means | What to tell the user |
|---|---|---|---|
| 100 | Faktura przyjęta do dalszego przetwarzania | Accepted for processing. Not final yet. | We've sent your invoice to KSeF and we're waiting for confirmation. |
| 150 | Trwa przetwarzanie | Still processing. Keep polling. | KSeF is still processing your invoice. This usually takes a moment. |
| 200 | Sukces | Accepted, and a KSeF number has been assigned. | Your invoice is issued. KSeF number: [number]. |
| 405 | Przetwarzanie anulowane z powodu błędu sesji | The whole session failed, so this invoice wasn't processed. | Something went wrong with the connection to KSeF, so this invoice wasn't sent. Your draft is saved. Try sending it again. |
| 410 | Nieprawidłowy zakres uprawnień | The sender doesn't have permission to issue invoices for this seller or context. | Your account doesn't have permission to issue invoices for this company in KSeF. Ask the company's administrator to grant it. |
| 415 | Brak możliwości wysyłania faktury z załącznikiem | The invoice has an attachment, and attachments aren't enabled for this taxpayer. | KSeF doesn't accept attachments for this company yet. Remove the attachment and send the invoice again. |
| 430 | Błąd weryfikacji pliku faktury | The file itself failed: not well-formed XML, the wrong encoding, or a schema mismatch. | This invoice couldn't be read by KSeF. This is a problem on our side, and we've been notified. |
| 435 | Błąd odszyfrowania pliku | KSeF couldn't decrypt the file, usually a key or IV problem. | This invoice couldn't be sent securely. This is a problem on our side, and we've been notified. |
| 440 | Duplikat faktury | An invoice with the same seller NIP, invoice type, and number already exists. KSeF returns the original KSeF number. | An invoice with this number was already sent to KSeF. Check the original before you send it again. |
| 450 | Błąd weryfikacji semantyki dokumentu faktury | A business rule failed, for example a date or a required field. | KSeF didn't accept this invoice because [field] is invalid. Fix it and send it again. Your draft is saved. |
| 500 | Nieznany błąd | Unknown error. | KSeF returned an error we didn't expect. Your draft is saved. Try again in a few minutes. |
| 550 | Operacja została anulowana przez system | KSeF cancelled the operation for internal reasons. | KSeF couldn't finish this right now. Your draft is saved. Try sending it again. |
Duplicates are checked across all of KSeF on the seller's NIP, the invoice type, and the invoice number, and the numbers stay unique for 10 full years. The NIP checksum is only verified in production, so an invoice with a mistyped NIP can pass on the test environment and fail once you go live. The official documentation doesn't say which status code that failure returns.
03Errors when you send an invoice
These come back straight away as HTTP 400 responses when you post an invoice to an online session.
| Code | Official name (Polish) | What it means |
|---|---|---|
| 21155 | — | The limit of invoices in this session has been reached. A session can hold up to 10,000 invoices. |
| 21402 | Nieprawidłowy rozmiar pliku. | The declared file size doesn't match the content. |
| 21403 | Nieprawidłowy skrót pliku. | The file hash doesn't match. |
| 21173 | — | The session wasn't found. |
| 21180 | Status sesji nie pozwala na wykonanie operacji. | The session's status doesn't allow this, usually because it's already closed. |
| 21184 | Sesja tymczasowo niedostępna. | The session is temporarily unavailable, for example during maintenance. Retry later or open a new session. |
| 21405 | Błąd walidacji danych wejściowych. | A general input validation error. It appears on dozens of endpoints, so read the details field. |
Invoices can be up to 1 MB without attachments and 3 MB with them. The XML has to be UTF-8 without a byte order mark.
04Authentication errors
Codes returned straight away (HTTP 400)
| Code | Official name (Polish) | What it means |
|---|---|---|
| 9101 | Nieprawidłowy dokument. | The signed authentication document isn't valid. |
| 9102 | Brak podpisu. | The request has no signature. |
| 9105 | Nieprawidłowy podpis. | The signature is invalid. |
| 21001 | Nieczytelna treść. | The request body can't be read. |
| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | The one-time challenge is wrong, expired, or already used. |
| 21115 | Nieprawidłowy certyfikat. | The certificate was rejected. |
| 21117 | Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu. | The NIP or identifier doesn't fit the context type you chose. |
| 21301 | Brak autoryzacji. | Not authorised, for example the tokens were already redeemed or the KSeF token was revoked. |
| 21470 | Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz. | The Ministry's public key you used for encryption is unknown or has been retired. Fetch the current keys. |
Authentication status codes
- 100: authentication in progress.
- 200: authentication succeeded.
- 415: failed, because the user has no permissions in that context.
- 425: the user revoked the authentication.
- 450: failed because of the token, for example an invalid, revoked, or inactive token.
- 460: failed because of the certificate, for example an invalid, revoked, or suspended certificate.
- 480: blocked because of a suspected security incident. The user has to contact the Ministry through its form.
- 550: cancelled by the system. Retry.
05Rate limits and downtime
When you send too many requests, KSeF returns HTTP 429 with a Retry-After header in seconds. The limits apply per second, per minute, and per hour at the same time, the block gets longer for repeat offences, and the test environment allows ten times more than production. Sending invoices, for example, is limited to 10 requests a second, 30 a minute, and 180 an hour.
There's no dedicated error code for KSeF being down. You'll see it as status 550, as exceptionCode 21184, or in the Ministry's technical notices. When KSeF is officially unavailable, the law allows offline modes, and invoices then have to be sent within set deadlines once the system is back.
06How to design the error states
Right now, a lot of invoicing apps show these codes to the user exactly as KSeF returns them. Instead, group the codes by what the user can do about them:
- Problems the user can fix, like a duplicate number, a missing permission, or an invalid field. Say what's wrong and where to fix it.
- Problems on your side, like file, encoding, or encryption errors. Don't ask the user to fix them. Log them and let the user know you're on it.
- Problems on KSeF's side, like statuses 500 and 550 or a temporarily unavailable session. Let the user know their draft is saved and retry for them if you can.
It's important that you keep the original code and the KSeF reference number below the message, for accountants and your support team who need to check it. We wrote more about this in our article on translating technical error codes into user-facing copy.
07Where these codes come from
Every code, name, and limit on this page comes from the Ministry of Finance's KSeF API repository on GitHub (github.com/CIRFMF/ksef-api), API version 2.9.0, checked on 25 October 2026. The suggested user messages are ours. The API changes often, so we'll keep this page updated, and if you spot a code we've missed, email us at hello@fessburn.com.