KSeF Error Codes
Overview
When something goes wrong while sending an invoice to KSeF (Krajowy System e-Faktur, Poland's National e-Invoice System), the response comes back with a numeric error code alongside a short message. The code is the stable part — the accompanying text can vary slightly between clients and gateway versions, but the code identifies the same underlying problem every time. That makes it worth learning the codes rather than just the wording next to them, especially if you ever see the same code surface in a different piece of software.
This page groups the codes Biurko recognises and explains into five families: authorisation and sessions, permissions, document structure checks, document logic, and outages. Find your code below, read what it actually means, and follow the suggested steps. If the code you got isn't listed here, see "What this list doesn't cover" at the end.
Authorisation and session errors
These errors happen before or during the handshake between your software and KSeF — establishing who you are and keeping that connection alive.
21100 — Invalid authorisation token
KSeF rejected the authorisation token used to start the connection. This usually means the token was malformed, already used, or generated against the wrong environment (for example a test-environment token sent to production, or vice versa). Discard the token and request a fresh one for the correct KSeF environment, then retry the connection.
21115 — Certificate rejected by KSeF
This is the most common certificate-related error, and also the one people misdiagnose most often, because the same code covers three unrelated causes. When you see 21115, work through them in order:
- The certificate isn't registered with KSeF. Every certificate used to authenticate has to be registered against the company's NIP (tax identification number) in the KSeF portal before it can be used to open a session. If that registration step was skipped or wasn't completed for this specific certificate, KSeF has no record of trusting it and refuses the connection.
- The NIP inside the certificate doesn't match the company's NIP. A certificate issued for one company cannot authenticate on behalf of a different one. This turns up most often when a certificate gets reused across companies, or when a new certificate was generated but the wrong entity's details ended up embedded in it.
- A session is already active for this certificate. KSeF only allows one active session per certificate at a time. If a previous session was never closed cleanly — a crashed process, a dropped connection, a browser tab left open — the certificate looks "busy" from KSeF's side even though nothing appears to be happening on your end.
To resolve it: confirm the certificate is registered against the correct NIP in the KSeF portal, check that you're using the certificate that actually belongs to the company you're sending for, and if neither of those is the issue, wait for any existing session to time out (or close it explicitly if you have access to do so) before reconnecting.
21175 — Challenge expired
KSeF issues a short-lived cryptographic challenge as the first step of authentication, and that challenge has to be answered within a limited window. If too much time passes between requesting the challenge and completing the signing step — often because of a slow certificate device, a manual signing step, or a stalled network — the challenge expires and the exchange has to restart. There's no fix beyond starting the connection again; if it keeps happening, look at what's slowing down the signing step.
21177 — Session already open for this certificate
KSeF is telling you a session tied to this certificate is still active, so it won't open a second one. This is the same underlying constraint as one of the causes of 21115, but returned directly when the rest of the handshake was otherwise fine. Either wait for the existing session to expire on its own, or explicitly disconnect it before reconnecting.
21178 — Session does not exist or was closed
The session token you're using no longer refers to anything KSeF recognises — either it never existed (a typo or a stale token from a previous integration), or the session behind it was already closed, expired, or revoked. Start a new session from scratch rather than trying to reuse the old token.
21179 — Too many open sessions
KSeF caps how many sessions can be open at once for a given account or certificate, and that cap has been reached. This can happen when several tools or processes are authenticating in parallel, or when old sessions are piling up without being closed. Wait a few minutes for older sessions to expire and retry; if this happens regularly, check whether something on your side is opening sessions without closing them.
21401 — Session token invalid or expired
The token identifying your current session is no longer valid — most often because the session has simply expired from inactivity. Reconnect to start a new session; there's no way to extend an expired one.
21402 — Session token revoked
The session token was explicitly revoked rather than left to expire naturally. This can happen if the session was closed from another client, from the KSeF portal, or as a security measure. Reconnect with a new session; if you didn't revoke it yourself, check whether someone else with access to the same credentials closed it.
21404 — Identity mismatch in token
The identity embedded in the session token doesn't match the identity that originally opened the session. This points to a token being reused across a different certificate or a different authenticated identity than the one it was issued for — usually a sign that a token got copied into the wrong place, or a session context got mixed up between two integrations running side by side. Re-authenticate cleanly with the identity you intend to use.
Permissions
Being authenticated with KSeF isn't the same as being allowed to do a specific action — these errors mean the identity is valid, but it lacks the right permission for what it's trying to do.
21330 — Not authorised to issue on behalf of the seller
The authenticated identity doesn't have permission to issue invoices for the seller's NIP named on the document. In KSeF, issuing on behalf of another entity (an accounting office acting for a client, for example) requires that permission to be granted explicitly in the KSeF portal — it isn't automatic just because you have valid credentials.
- Check the permissions granted for this certificate or identity in the KSeF portal.
- Confirm the seller's NIP on the invoice actually matches an entity you're authorised to act for.
- If the permission should exist but doesn't show up, contact whoever administers KSeF access for that company.
21331 — Not authorised to read invoices for this NIP
Similar to 21330, but for reading rather than issuing: the identity is trying to fetch or list invoices for a NIP it doesn't have read access to. Grant the appropriate read permission in the KSeF portal, or confirm you're querying the NIP you actually meant to.
Document structure checks
KSeF validates every invoice against a strict schema before it accepts it. These codes mean the document itself — its structure, formatting, or a required value — didn't pass that check. They're almost always fixable by correcting the invoice data and resending; they don't indicate a connection or permissions problem.
21301 — Invoice failed XSD validation
The invoice XML doesn't conform to the XSD schema KSeF expects — the file's overall structure is malformed, a tag is out of order, or an element has the wrong shape. This is usually a symptom of a more specific problem elsewhere on this list (a missing field, an invalid format), but if the message doesn't point to anything more precise, check the invoice against the current KSeF schema version rather than an older one.
21302 — Invalid invoice number format
The invoice number doesn't match the format KSeF expects for that field. This is different from the invoice already existing (see 21501) — here the number itself is malformed, for example containing characters or a length that the schema rejects.
21303 — Missing required field
The invoice is missing a value in a field KSeF requires. Which field is missing is normally named in the accompanying error text — check that detail rather than guessing, since this code covers any required field, not one specific one. Fill in the missing value and resend.
21304 — Invalid buyer or seller NIP
The NIP given for the buyer or the seller doesn't pass validation — it may have the wrong number of digits, fail the checksum KSeF applies to NIPs, or simply not exist as a registered tax identifier. Double-check the NIP against the counterparty's actual registration details before resending.
21305 — Invalid issue date
The invoice's issue date is outside what KSeF will accept — for example a date in the future, or one formatted incorrectly. Correct the date and resend.
21306 — Invalid VAT rate values
One or more VAT rates on the invoice don't match a rate KSeF recognises as valid for the document type or period. This can happen with a typo in the rate, or with a rate that's legitimate in general but not applicable to the specific invoice type being sent. Review each line's VAT rate against what's currently permitted.
21307 — Invalid currency code
The currency code on the invoice isn't a valid ISO code, or isn't one KSeF accepts in this context. Check the code against the ISO 4217 standard (for example PLN, EUR) and correct any typo.
21308 — No line items
KSeF requires at least one line item on the invoice, and none were found. This usually points to an invoice generated with an empty items list — check whatever produced the document before resending.
21309 — Invalid exchange rate
The invoice includes an exchange rate that KSeF doesn't consider valid — for example a missing rate on a foreign-currency invoice that requires one, or a rate that doesn't correspond to the date it should be taken from. Verify the rate and the date it's tied to.
21310 — Invoice hash mismatch
The invoice's checksum (HashFA) doesn't match the content of the document it's supposed to protect. In practice this means the invoice file was altered, corrupted, or regenerated after the hash was calculated, so the two no longer line up. Regenerate the hash from the final version of the invoice and resend — don't reuse a hash calculated before the last edit.
Document logic
These errors aren't about the invoice's structure — the document is well-formed, but the action being requested doesn't make sense given what KSeF already knows about it.
21501 — Invoice already submitted
An invoice with this number has already been sent to KSeF successfully. Sending it again under the same number isn't possible — if the invoice needs a correction, issue a correcting invoice instead of resending the original.
21502 — KSeF number does not exist
The KSeF number referenced in the request doesn't exist in the system. This typically comes up when trying to look up, correct, or reference an invoice by a KSeF number that was mistyped, belongs to a different environment (test vs. production), or was never actually assigned. Double-check the number against the confirmation you received when the original invoice was accepted.
21503 — Corrected invoice does not exist in KSeF
You're issuing a correction, but the invoice it's meant to correct can't be found in KSeF under the reference given. Confirm the original invoice's KSeF number is correct and that it was in fact accepted by KSeF (rather than, say, only saved locally or rejected earlier).
21504 — Cannot correct an invoice already corrected to zero
The invoice you're trying to correct has already been reduced to zero by a previous correction, and KSeF won't accept a further correction on top of that — a zeroed-out invoice is treated as fully settled. If further changes are needed, they have to be handled through a new invoice rather than another correction to the same one.
Outages and unexpected failures
These codes aren't about your invoice at all — they mean KSeF itself is temporarily unavailable, or something happened that doesn't fit any of the categories above.
21900 — KSeF temporarily unavailable
KSeF's own infrastructure is not responding normally right now — this is on KSeF's side, not a problem with the invoice or your credentials. In Biurko, this situation is handled automatically: sending is queued and retried once KSeF is reachable again, so there is usually nothing to do beyond waiting.
21901 — Emergency mode active
KSeF has declared an emergency (failure) mode, meaning the system as a whole is not accepting invoices normally. Invoices can still be issued offline during this period and are transmitted to KSeF once the outage ends. The deadline for sending them afterwards depends on which offline mode applied:
- Under the offline24 mode, an invoice issued offline must be transmitted to KSeF no later than the next business day following the day it was issued.
- Under full emergency (awaryjny) mode, invoices must be transmitted within 7 business days of the end of the outage.
Biurko queues invoices issued during an outage and retries transmission automatically once KSeF confirms it's accepting documents again, so this deadline is tracked for you rather than something you need to calculate by hand.
21999 — Unexpected KSeF error
A generic code KSeF returns when something failed in a way that doesn't map to any of the specific errors above. Because it's a catch-all, there's no single fix — check the accompanying message text for any additional detail, and if it doesn't clarify anything, contact your administrator or KSeF support with the full error text and the time it occurred.
What this list doesn't cover
This page covers the error codes Biurko specifically recognises and surfaces with a tailored explanation. KSeF's API defines other codes beyond these, and you may occasionally receive one that isn't listed here — particularly for less common operations than issuing and receiving invoices. If that happens, read the message text returned alongside the code, since it usually describes the specific condition that triggered it, and if it's still unclear, reach out to support with the exact code and message.