Overview
KSeF reports problems as exception codes in the response body alongside an HTTP status, and the code — not the HTTP number alone — tells you what actually failed. Common causes are an invalid authentication challenge, an invalid certificate, or an invoice that fails the FA(3) schema and is then reported as not correctly processed. Read the Polish description against the official KSeF code table instead of guessing, because the same numeric code can mean different things in different endpoints.
How KSeF reports errors
KSeF (Krajowy System e-Faktur) is Poland's national e-invoicing platform operated by the Ministry of Finance (Ministerstwo Finansów). When a call fails, the response contains an exception code such as 21111 or 21401 plus a description in Polish. These codes are documented in the KSeF API specification, and they are the reliable signal for your retry logic and your support team.
Authentication codes
Authentication failures surface as codes on the authentication endpoints. For example, 21111 means an invalid authorization challenge (both for the token path and the XAdES path), 21115 means an invalid certificate on the XAdES path, and 21301 or 21304 mean the authorization or authentication is missing or no longer valid — for instance when a token has been revoked. Fix the credential or the challenge before retrying.
Invoice and session codes
Once you are in a session, other codes appear. 21401 means a document did not conform to the XSD schema — but on the /v2/auth/xades-signature endpoint it refers to the XAdES document used for the certificate-based authentication path, not to the FA(3) invoice. 21155 means the session reached its invoice limit, 21173 means the session was not found, 21180 means the session status does not allow the operation, and 21184 means the session is temporarily unavailable. A FA(3) invoice that fails the schema is reported in the processing status — the invoice appears as not correctly processed (nieprawidłowo przetworzona) in the session's failed-invoices listing — rather than as a 21401 exception on the submit call.
The 422 case in Notaly
422 is not a KSeF code in this flow. In Notaly it means the payload failed Notaly's own validation before it reached KSeF — for example a seller NIP that does not match the sandbox value 2745013933. Fixing the payload is the answer, not retrying the same data.
A simple troubleshooting order
Check the code and description first, then act by category: credential problem, schema problem, session problem, or payload problem. For timeouts, retry with a stable idempotency key and verify the invoice status before resubmitting, so you never create a duplicate.
FAQ
What does a 400 from KSeF mean? A 400 carries an exception code in the body that describes the specific problem, such as an invalid challenge, an invalid certificate, or — on the XAdES endpoint — a document that fails the schema.
Is 422 a KSeF code? No. In Notaly, 422 means the payload failed Notaly's own validation before it reached KSeF.
Disclaimer
Notaly is not a tax, accounting or legal advisor. This article is general information, not tax advice, and may be outdated. You are responsible for your own VAT compliance; confirm with a qualified accountant where required.
Sources
Source: api-test.ksef.mf.gov.pl