Codici di stato e di errore KSeF spiegati
Quando KSeF, il sistema nazionale polacco di fatturazione elettronica, non accetta una fattura, assegna alla fattura un codice di stato, come 440 o 450, oppure risponde alla richiesta con un codice di errore, come 21405. Cerca qui sotto il tuo codice: trovi cosa significa, la causa più comune e cosa cambiare prima di inviare di nuovo la fattura.
In breve
Cosa significano i codici di stato e di errore di KSeF, come 440, 450 o 21405, perché il sistema polacco non ha accettato la fattura e cosa correggere.
Questo elenco include 32 codici presenti nei documenti ufficiali qui sotto. 5 hanno una pagina dedicata; 27 sono spiegati solo nella tabella, perché sono stati di sistema o di trasporto e nella fattura non c'è nulla da correggere.
Non inclusi: 21111, 21115, 21117, 21217, 21301, 21304, 21308, 21401, 21406, 9101, 9102, 9103, 9105, 21164, 21165, 21175, 21181, 21182, 21183, 21418, 25001, 25002, 25003, 25004, 25005, 25006, 25007, 25008, 25009, 25010, 25011, 26001, 26002, 30001, 71001, 71002, 71004, 71005, che riguardano un processo diverso dall'invio di una fattura.
Codici di stato della fattura
| Codice | Cosa significa |
|---|---|
| 405 | Elaborazione annullata per un errore di sessione KSeF 405, come stato della fattura, indica che l'elaborazione della fattura è stata annullata a causa di un errore nella sessione in cui è stata inviata. Correggi ciò che indica lo stato della sessione, poi invia di nuovo la fattura in una nuova sessione. |
| 410 | Nessuna autorizzazione per emettere questa fattura |
| 415 | Fattura con allegato non accettata |
| 430 | Il file della fattura non ha superato il controllo |
| 435 | Il file della fattura non si è potuto decifrare KSeF 435, come stato della fattura, indica che KSeF non è riuscito a decifrare il file della fattura. Chiedi a chi ti fornisce il software di controllare la cifratura, poi invia di nuovo la fattura. |
| 440 | Fattura duplicata |
| 450 | Il contenuto della fattura non ha superato i controlli |
| 500 | Errore sconosciuto KSeF 500 indica che si è verificato un errore sconosciuto mentre KSeF elaborava la fattura o la sessione. Controlla di nuovo lo stato più tardi. Se resta 500, contatta l'assistenza di KSeF indicando il numero di riferimento, prima di decidere se inviare di nuovo la fattura. |
| 550 | Operazione annullata dal sistema KSeF 550 indica che il sistema ha annullato l'operazione. Riprova, come consiglia la documentazione di KSeF. |
Codici di stato della sessione
| Codice | Cosa significa |
|---|---|
| 405 | Il pacchetto batch non ha superato il controllo KSeF 405, come stato della sessione, indica che gli elementi del pacchetto batch non hanno superato il controllo di KSeF. Chiedi a chi ti fornisce il software di controllare come il pacchetto viene costruito e dichiarato, poi invialo in una nuova sessione batch. |
| 415 | La chiave della sessione non si è potuta decifrare KSeF 415, come stato della sessione, indica che KSeF non è riuscito a decifrare la chiave fornita. Chiedi a chi ti fornisce il software di controllare la cifratura della chiave e la chiave pubblica che usa, poi apri una nuova sessione e invia di nuovo le fatture. |
| 420 | Troppe fatture nella sessione KSeF 420, come stato della sessione, indica che la sessione ha superato il limite di fatture. Dividi le fatture in più sessioni e inviale di nuovo. |
| 430 | Archivio del lotto non decomprimibile KSeF 430 (stato della sessione): KSeF non è riuscito a decomprimere l'archivio ZIP originale del lotto. Chiedi all'assistenza del tuo software di ricreare il pacchetto, poi invialo in una nuova sessione batch. |
| 435 | Parti dell'archivio non decifrabili KSeF 435 (stato della sessione): KSeF non è riuscito a decifrare le parti cifrate dell'archivio del lotto. Chiedi all'assistenza del tuo software di verificare la cifratura delle parti, poi invia il pacchetto in una nuova sessione batch. |
| 440 | Sessione annullata KSeF 440 (stato della sessione): la sessione è stata annullata. Apri una nuova sessione e invia le fatture entro il tempo consentito. |
| 445 | Nessuna fattura valida nella sessione KSeF 445 (stato della sessione): il controllo non ha trovato nessuna fattura valida nella sessione. Correggi gli errori segnalati sulle singole fatture, verifica che nella sessione ci siano fatture valide e invia di nuovo le fatture. |
Codici di errore durante l'invio
| Codice | Cosa significa |
|---|---|
| 21001 | Contenuto della richiesta non leggibile KSeF 21001: KSeF non è riuscito a leggere il contenuto della richiesta. Chiedi all'assistenza del tuo software di controllare la richiesta in base ai dettagli, poi inviala di nuovo. |
| 21155 | Troppe fatture nella sessione KSeF 21155: la sessione ha raggiunto il numero di fatture consentito. Chiudi la sessione e invia le fatture rimanenti in una nuova sessione. |
| 21157 | Dimensione errata di una parte del pacchetto KSeF 21157: la dimensione di una parte del pacchetto batch non è valida. Ricostruisci il pacchetto in modo che ogni parte rientri nel limite e corrisponda alla dimensione dichiarata, poi invialo in una nuova sessione batch. |
| 21161 | Troppe parti nel pacchetto KSeF 21161: il pacchetto batch ha più parti di quelle che KSeF consente. Distribuisci le fatture su più sessioni batch e inviale di nuovo. |
| 21166 | Correzione tecnica non disponibile KSeF 21166: non si può inviare una correzione tecnica, perché per la fattura ne esiste già una che KSeF ha elaborato correttamente. Controlla lo stato della correzione tecnica precedente invece di inviarne un'altra. |
| 21167 | Lo stato della fattura non consente la correzione tecnica KSeF 21167: è stata inviata una correzione tecnica per una fattura che KSeF ha elaborato correttamente. Verifica che hashOfCorrectedInvoice contenga l'hash della fattura offline rifiutata, non quello di una fattura accettata. |
| 21173 | Sessione non trovata KSeF 21173: non esiste nessuna sessione con il numero di riferimento indicato. Usa il numero di riferimento corretto della sessione e invia di nuovo la richiesta. |
| 21178 | UPO non trovato KSeF 21178: KSeF non ha trovato nessun UPO, la ricevuta ufficiale, per i criteri indicati. Correggi i numeri e richiedi di nuovo l'UPO. |
| 21180 | Lo stato della sessione non consente l'operazione KSeF 21180 indica che lo stato della sessione non permette l'operazione richiesta, per esempio inviare fatture o chiudere la sessione. Controlla lo stato della sessione e apri una nuova sessione per inviare altre fatture. |
| 21184 | Sessione temporaneamente non disponibile KSeF 21184 indica che la sessione non è disponibile per il momento a causa di lavori di manutenzione. Riprova più tardi, oppure apri una nuova sessione per inviare altre fatture, come indicano i dettagli dell'errore. |
| 21205 | Pacchetto vuoto: manca una parte dichiarata KSeF 21205 indica che il pacchetto non può essere vuoto: una delle parti dichiarate non è stata inviata. Invia la parte mancante indicata nei dettagli e verifica che tutte le parti dichiarate siano state inviate. |
| 21208 | Tempo per l'invio scaduto KSeF 21208 indica che è scaduto il tempo concesso per le richieste upload o finish e che la sessione è stata annullata. Apri una nuova sessione batch e invia le parti entro il tempo consentito. |
| 21402 | Dimensione del file non corretta KSeF 21402 indica che la lunghezza del contenuto inviato non corrisponde alla dimensione dichiarata del file. Chiedi all'assistenza del tuo software di controllare che la dimensione dichiarata sia quella del file inviato, poi invia di nuovo. |
| 21403 | Hash del file non corretto KSeF 21403 indica che l'hash del contenuto inviato non corrisponde all'hash dichiarato del file. Chiedi all'assistenza del tuo software di verificare che l'hash dichiarato sia calcolato sul file inviato, poi invia di nuovo. |
| 21405 | I dati della richiesta non hanno superato il controllo KSeF 21405 indica che i dati della richiesta non hanno superato il controllo. Correggi ciò che i dettagli indicano e invia di nuovo la richiesta. |
| 21470 | Chiave sconosciuta o ritirata KSeF 21470 indica che l'identificatore della chiave inviato è sconosciuto oppure si riferisce a una chiave ritirata. Chiedi all'assistenza del tuo software di usare un identificatore di chiave supportato, poi invia di nuovo la richiesta. |
Leggi il documento ufficiale
- KSeF API 2.0, specyfikacja OpenAPI (open-api.json) Fonte: KSeF API 2.0, specyfikacja OpenAPI (open-api.json), versione 2.9.0, pubblicata da Ministerstwo Finansów, consultata il 8 novembre 2026. Testo ufficiale in lingua originale, da Ministerstwo Finansów, KSeF 2.0 Przewodnik dla Integratorów (github.com/CIRFMF/ksef-api), Copyright (c) 2025 Ministerstwo Finansów, con licenza MIT License.
- Weryfikacja faktury Fonte: Weryfikacja faktury, versione 09.04.2026, pubblicata da Ministerstwo Finansów, consultata il 8 novembre 2026. Testo ufficiale in lingua originale, da Ministerstwo Finansów, KSeF 2.0 Przewodnik dla Integratorów (github.com/CIRFMF/ksef-api), Copyright (c) 2025 Ministerstwo Finansów, con licenza MIT License.
Domande frequenti
Dove vedo lo stato KSeF di una fattura?
Il tuo programma di fatturazione lo legge da KSeF dopo l'invio: ogni fattura di una sessione riceve un codice di stato, una descrizione e, quando KSeF li fornisce, dei dettagli. Lo stato 200 indica che è andato tutto a buon fine, mentre 100 e 150 indicano che KSeF sta ancora elaborando la fattura.
Perché lo stesso numero compare due volte?
KSeF usa gli stessi numeri per lo stato di una fattura e per lo stato di una sessione, con significati diversi. Per una fattura 440 indica un duplicato, per una sessione indica che la sessione è stata annullata. Controlla quale dei due mostra il tuo programma.
Quali codici non sono elencati?
Gli stati che indicano avanzamento o esito positivo, e i codici di errore per l'accesso, i certificati, i token, le autorizzazioni e lo scaricamento delle fatture, che riguardano un processo diverso dall'invio di una fattura.
Da dove arrivano i codici?
Dalla documentazione dell'API KSeF 2.0 del Ministero delle Finanze polacco, pubblicata con licenza MIT. Ogni pagina riporta il testo ufficiale in polacco e il link alla fonte.