KSeF Error Codes Explained: How to Handle FA_VAT Rejections
Complete guide to KSeF rejection codes and error handling. What each FA_VAT validation error means, how to fix it, and what to do during KSeF downtime.
KSeF Error Codes Explained: How to Handle FA_VAT Rejections
One of the most frustrating aspects of KSeF is what happens when your invoice is rejected. Unlike traditional invoicing (where you just send a PDF and hear nothing), KSeF returns a structured response for every submission. When something is wrong, you need to understand what the rejection code means and fix it quickly — because an invalid invoice has no legal standing for VAT purposes in Poland.
This guide explains the most common KSeF rejection categories, what they mean in practice, and what to do about them.
How KSeF Validation Works
When you submit a FA_VAT XML invoice to the KSeF API, the platform performs two levels of validation:
Level 1: Schema Validation
KSeF first validates the XML against the official FA_VAT XSD schema. This checks:
- All required fields are present
- Data types are correct (dates in ISO 8601, amounts as decimal numbers)
- Enumerated values use the correct codes (e.g., VAT rate codes, invoice type codes)
If schema validation fails, KSeF returns a rejection immediately with an HTTP error response and a structured error object identifying the offending XML path.
Level 2: Business Rules Validation
After schema validation passes, KSeF checks business logic:
- Your NIP (tax ID) is registered and active in the KSeF system
- The buyer's NIP is valid (checked against the CEIDG/KRS registry)
- Invoice totals are internally consistent (line items sum to header totals)
- VAT calculations are correct
- The invoice number does not duplicate an existing KSeF submission
Business rule failures return a structured response with an error code and description.
Common KSeF Error Categories
1. Schema/Format Errors
Error type: SchemaValidationError
These occur when the XML does not conform to the FA_VAT XSD schema.
| Common cause | Fix |
|---|---|
Missing required field (e.g., P_2 invoice number, P_1 issue date) |
Add the missing field to your invoice template |
Wrong date format (e.g., 01/04/2026 instead of 2026-04-01) |
Use ISO 8601 format: YYYY-MM-DD |
| Wrong decimal separator (comma instead of period) | Use period as decimal separator: 100.00 not 100,00 |
| Encoding issue (special characters not UTF-8) | Ensure your XML is encoded as UTF-8 |
| Invalid enumeration value for VAT type code | Use the correct enum value from the FA_VAT documentation |
Where to find the FA_VAT schema: The current XSD schema and associated documentation is published by the Ministerstwo Finansów at podatki.gov.pl/ksef.
2. Authorisation Errors
Error type: AuthenticationError / AuthorisationError
These occur when the KSeF token is invalid, expired, or does not have the right permissions.
| Error code | Meaning | Fix |
|---|---|---|
401 Unauthorized |
Token missing or malformed | Check your API call includes the SessionToken header |
| Token expired | KSeF tokens expire after a set period | Re-authenticate using your initialisation token to get a new session token |
| NIP mismatch | The NIP in the invoice does not match the authenticated NIP | Ensure you are submitting on behalf of the correct taxpayer NIP |
| Missing role | Your token has read-only access, not write | Request a token with the Invoice_Write role |
3. Business Rule Errors
Error type: BusinessRuleViolation
These are the most varied errors and require understanding the FA_VAT business rules.
| Common violation | Meaning | Fix |
|---|---|---|
| Invalid buyer NIP | The NIP you provided for the buyer is not registered | Verify the buyer's NIP at portal.podatki.gov.pl |
| Duplicate invoice number | You have already submitted an invoice with this number/NIP combination | Use a unique invoice identifier; check your invoice numbering sequence |
| VAT calculation mismatch | The VAT amount does not match the rate × base | Recalculate: VAT = round(NetAmount × VATRate / 100, 2) |
| Invoice total mismatch | Sum of line items does not equal the header total | Reconcile line items and header; rounding must be consistent |
| Invalid VAT rate code | The VAT rate code used does not exist in the FA_VAT enumeration | Use the correct Polish VAT rate codes: A (23%), B (8%), C (5%), D (0%), E (exempt) |
4. NIP Registry Errors
Error type: EntityNotFoundError
These occur when KSeF cannot find the taxpayer in its registry.
- Your own NIP not found: This is rare if you are already using KSeF, but can happen for new registrations. Contact your Urząd Skarbowy (tax office).
- Buyer NIP not found: More common. This can happen if the buyer is:
- Recently registered (registry update lag of up to 1 business day)
- Not VAT-registered (for consumers or VAT-exempt entities — use different invoice handling)
- Registered under a different entity type (e.g., a foreign company)
Handling KSeF Downtime
KSeF outages are a documented risk. The original July 2024 mandatory date was postponed partly due to platform stability concerns. Even after the remediation work, businesses should plan for occasional KSeF unavailability.
Offline Mode in the FA_VAT regulation
The Polish KSeF regulation includes a legal offline mode for situations when KSeF is unavailable. Key rules:
- When KSeF is unavailable, you may issue invoices outside KSeF using the offline FA_VAT format
- You must include a specific XML element (
KSeF:Offline) indicating the invoice was issued in offline mode - Within 7 days of KSeF returning to availability, all offline invoices must be submitted to KSeF retroactively
- The buyer can use the offline invoice for VAT deduction immediately, without waiting for the KSeF reference number
- The Ministry of Finance publishes KSeF status at status.podatki.gov.pl
What your software should do
Good KSeF-integrated software should:
- Monitor KSeF availability automatically
- Switch to offline mode seamlessly when KSeF is down
- Queue offline invoices for retroactive submission
- Alert you to the retroactive submission deadline (7 days after KSeF recovery)
If your software does not support offline mode, you need to manage this manually — which is operationally very risky. Consider upgrading to software with built-in offline support.
Testing Your Integration Before Go-Live
The Ministerstwo Finansów provides a test environment (the KSeF Demo system) where you can submit test invoices without creating real legal obligations.
- Test environment:
ksef-demo.mf.gov.pl - Documentation: podatki.gov.pl/ksef/
- Test NIP: The Ministry publishes test NIPs for use in the demo environment
Test scenarios you should run before going live:
- Happy path: Valid invoice submitted and KSeF reference number returned
- Schema error: Missing required field — verify your error handling
- VAT calculation error: Off-by-one cent — understand the rounding rules
- Duplicate submission: Same invoice number submitted twice
- Offline mode: Simulate KSeF unavailability and retroactive submission
Resources
- Official KSeF documentation: podatki.gov.pl/ksef
- FA_VAT XSD schema: Published in the official Polish Journal of Laws (Dziennik Ustaw) and available at the Ministerstwo Finansów website
- KSeF status page: status.podatki.gov.pl
- NIP lookup: portal.podatki.gov.pl
- KSeF e-Urząd portal: efaktura.gov.pl