Riferimento codici di errore

Questa pagina è il riferimento centralizzato per le risposte di errore di tutte le API fiskaly. Usa l’explorer interattivo qui sotto per cercare e filtrare gli errori, oppure scorri verso il basso per le tabelle di riferimento statiche.

36 errors found

Riferimento statico

Inizia dall’albero decisionale per la risoluzione dei problemi se hai un errore e hai bisogno di una risposta rapida, oppure consulta le tabelle specifiche per prodotto per i codici di errore dettagliati.

Formato della risposta di errore

Tutte le API fiskaly restituiscono gli errori in un formato JSON consistente:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Una descrizione leggibile di cosa è andato storto"
}

Campo	Tipo	Descrizione
`status_code`	intero	Codice di stato HTTP
`error`	stringa	Testo di stato HTTP
`code`	stringa	Codice di errore specifico di fiskaly (prefissato con `E_`)
`message`	stringa	Descrizione dell’errore leggibile

Codici di stato HTTP

2xx — Successo

Codice	Significato	Quando appare
`200`	OK	La richiesta è riuscita; il corpo della risposta contiene il risultato
`201`	Creato	Risorsa creata con successo
`204`	Nessun contenuto	La richiesta è riuscita, nessun corpo di risposta (es. operazioni DELETE)

4xx — Errori del client

Questi indicano un problema con la tua richiesta. Non riprovare con lo stesso payload — correggi prima il problema.

Codice	Significato	Cause comuni
`400`	Richiesta non valida	JSON malformato, campi obbligatori mancanti, valori di campo non validi
`401`	Non autorizzato	Token di accesso scaduto o mancante, credenziali API non valide
`403`	Proibito	Permessi insufficienti per la risorsa richiesta
`404`	Non trovato	La risorsa non esiste, o percorso URL errato
`409`	Conflitto	La risorsa esiste già (tentativo di creazione duplicata)
`422`	Entità non processabile	JSON valido ma semanticamente errato (es. transizione di stato non valida)
`423`	Bloccato	La risorsa è attualmente bloccata da un’altra operazione
`429`	Troppe richieste	Limite di frequenza superato — attendi e riprova con ritardo esponenziale

5xx — Errori del server

Questi indicano un problema temporaneo sul lato fiskaly. Sicuro da riprovare con backoff esponenziale.

Codice	Significato	Azione
`500`	Errore interno del server	Riprova dopo un breve ritardo; se persiste, controlla status.fiskaly.com
`502`	Gateway non valido	Servizio upstream temporaneamente non disponibile; riprova
`503`	Servizio non disponibile	Il servizio è temporaneamente in manutenzione; riprova
`504`	Timeout del gateway	La richiesta è scaduta a monte; riprova con timeout maggiore

Errori di autenticazione

Questi sono gli errori più comuni che gli sviluppatori incontrano durante l’integrazione.

Codice di errore	Stato HTTP	Causa	Soluzione
`E_UNAUTHORIZED_ACCESS`	401	Token di accesso scaduto o non fornito	Ri-autenticati usando la tua chiave e il tuo segreto API
`E_INVALID_CREDENTIALS`	401	La chiave o il segreto API è errato	Verifica le credenziali nell’HUB
`E_TOKEN_EXPIRED`	401	Il token di accesso JWT è scaduto	Usa il token di aggiornamento o ri-autenticati
`E_ACCESS_FORBIDDEN`	403	La tua chiave API non ha il permesso per questa risorsa	Controlla gli ambiti della chiave API nell’HUB

Ciclo di vita del token

Chiave API + Segreto  →  POST /auth  →  access_token (24h) + refresh_token (48h)
                                             │
                                             ├── Usa per tutte le chiamate API
                                             │
                                             └── Con 401 → ri-autenticati (non ad ogni richiesta)

💡Non ri-autenticarti ad ogni richiesta

L’access token è valido per 24 ore e il refresh token per 48 ore. Ri-autenticarsi ad ogni richiesta aggiunge latenza non necessaria al processo di checkout. Metti in cache il token e aggiornalo solo quando ricevi una risposta 401.

SIGN DE — Errori TSS

Codice di errore	Stato HTTP	Causa	Soluzione
`E_TSS_NOT_FOUND`	404	L’ID del TSS non esiste	Verifica l’ID del TSS; elenca tutti i TSS tramite `GET /tss`
`E_TSS_NOT_INITIALIZED`	400	Il TSS non è ancora stato inizializzato	Segui tutti i passi necessari: crea il TSS, aggiornalo a `UNINITIALIZED`, imposta il PIN Admin, accedi come Admin e imposta il TSS a `INITIALIZED`
`E_TSS_DISABLED`	400	Il TSS è stato disabilitato	Il TSS non può più firmare transazioni; crea un nuovo TSS
`E_TSS_IN_USE`	409	Il TSS è in corso di modifica da un’altra richiesta	Attendi e riprova
`E_CLIENT_NOT_FOUND`	404	L’ID del client non esiste per questo TSS	Crea un client tramite `PUT /tss/{tss_id}/client/{client_id}`
`E_CLIENT_NOT_REGISTERED`	400	Il client esiste ma non è registrato	Registra il client prima di creare transazioni
`E_TX_NOT_FOUND`	404	L’ID della transazione non esiste	Verifica l’ID della transazione e il contesto del TSS
`E_TX_INVALID_STATE`	422	La transazione è in uno stato che non permette questa operazione	Controlla lo stato attuale della transazione; segui la macchina a stati
`E_EXPORT_NOT_FOUND`	404	L’ID di esportazione non esiste	Verifica l’ID di esportazione; le esportazioni possono richiedere tempo per elaborarsi
`E_EXPORT_IN_PROGRESS`	409	L’esportazione è ancora in corso di generazione	Sonda lo stato dell’esportazione fino a `state: COMPLETED`

Errori SUBMIT DE

Codice di errore	Stato HTTP	Causa	Soluzione
`E_ESTABLISHMENT_NOT_FOUND`	404	ID stabilimento non trovato	Verifica che lo stabilimento esiste per la tua organizzazione
`E_TAXPAYER_NOT_FOUND`	404	Record del contribuente non trovato	Crea prima la risorsa contribuente
`E_TAXPAYER_ADDRESS_NOT_FOUND`	404	Indirizzo del contribuente non configurato	Aggiungi dati di indirizzo alla risorsa contribuente
`E_TAXPAYER_PERSON_NOT_FOUND`	404	Record persona del contribuente mancante	Aggiungi dati persona alla risorsa contribuente
`E_SUBMISSION_NOT_FOUND`	404	ID dichiarazione non trovato	Verifica l’ID dichiarazione; controlla che la dichiarazione sia stata creata
`E_CLIENT_ADDITIONAL_DATA_NOT_FOUND`	404	Dati aggiuntivi del client mancanti	Fornisci i dati aggiuntivi richiesti per il client
`E_LOCKED_RESOURCE`	423	La risorsa è bloccata da un’operazione in corso	Attendi il completamento dell’operazione corrente, poi riprova

Errori DSFINVK DE

Codice di errore	Stato HTTP	Causa	Soluzione
`E_CASH_REGISTER_NOT_FOUND`	404	Registratore di cassa non trovato	Crea prima il registratore di cassa tramite l’API DSFinV-K
`E_CASH_POINT_CLOSING_NOT_FOUND`	404	Chiusura punto cassa non trovata	Verifica l’ID di chiusura
`E_VAT_DEFINITION_NOT_FOUND`	404	Definizione IVA non configurata	Crea le definizioni IVA prima di inserire le chiusure
`E_INVALID_CLOSING_DATA`	400	Il payload di chiusura non corrisponde allo schema atteso	Valida il tuo payload rispetto alla specifica DSFinV-K

API Unificata — Errori comuni

Questi errori sono condivisi da tutti i prodotti dell’API Unificata (SIGN FR, SIGN IT, SIGN ES).

Codice di errore	Stato HTTP	Causa	Soluzione
`E_ORGANIZATION_NOT_FOUND`	404	L’ID organizzazione non esiste	Verifica l’ID org; assicurati sia stata creata sotto il GROUP corretto
`E_TAXPAYER_NOT_COMMISSIONED`	400	Il contribuente esiste ma il suo stato non è `COMMISSIONED`	Aggiorna lo stato del contribuente a `COMMISSIONED` prima di operare
`E_IDEMPOTENCY_KEY_REUSED`	409	La chiave di idempotenza è già stata usata per un’altra richiesta	Genera un nuovo UUID per ogni nuova richiesta
`E_API_VERSION_NOT_SUPPORTED`	400	L’header `X-Api-Version` contiene una data non supportata	Usa la versione più recente supportata (es. `2026-02-03`)
`E_SCOPE_IDENTIFIER_MISSING`	400	Header `X-Scope-Identifier` non fornito	Includi l’ID organizzazione in `X-Scope-Identifier`
`E_SUBJECT_NOT_FOUND`	404	Subject (chiave API) non trovato	Verifica che il subject sia stato creato sotto l’organizzazione corretta
`E_TOKEN_INVALID`	401	Il token è malformato o scaduto	Ri-autenticati tramite `POST /api/v1/auth/token`
`E_LOCATION_NOT_COMMISSIONED`	400	La sede esiste ma non è comissionata	Aggiorna lo stato della sede a `COMMISSIONED`
`E_SYSTEM_NOT_COMMISSIONED`	400	Il sistema esiste ma non è commissionato	Aggiorna lo stato del sistema a `COMMISSIONED`

💡Chiavi di idempotenza in tutte le API Unificate

Tutti i prodotti dell’API Unificata supportano l’header X-Idempotency-Key sulle richieste mutanti. Le coppie chiave-valore scadono dopo 24 ore. Se riusi una chiave con un payload diverso, riceverai un 422 Unprocessable Entity. Se la richiesta originale è ancora in elaborazione, riceverai un 409 Conflict.

SIGN FR — Errori specifici

Codice di errore	Stato HTTP	Causa	Soluzione
`E_RECORD_INVALID_OPERATION`	422	Il tipo di operazione del record non è valido per lo stato corrente	Controlla il flusso Intention → Transaction; assicura la sequenza corretta
`E_RECORD_INTENTION_REQUIRED`	400	Record di transazione creato senza Intention precedente	Crea prima un record Intention, poi referenzia il suo ID
`E_TAXPAYER_CREDENTIALS_INVALID`	400	Le credenziali di fiscalizzazione francese (NF 525) non sono valide	Verifica `tax_id_number` (SIREN) e le credenziali
`E_CLOSURE_IN_PROGRESS`	409	Una chiusura fiscale è già in corso	Attendi il completamento della chiusura corrente

SIGN IT — Errori specifici

Codice di errore	Stato HTTP	Causa	Soluzione
`E_RT_DEVICE_NOT_FOUND`	404	Dispositivo Registratore Telematico non trovato	Verifica che il dispositivo RT sia stato creato e commissionato
`E_RT_SUBMISSION_FAILED`	502	Invio ad Agenzia delle Entrate fallito	Riprova; controlla lo stato del servizio AdE se persiste
`E_LOTTERY_CODE_INVALID`	400	Il formato del codice della lotteria degli scontrini non è valido	Assicurati che il codice della lotteria sia di 8 caratteri alfanumerici
`E_FISCAL_CODE_INVALID`	400	Il formato del codice fiscale italiano è errato	Verifica il formato del codice fiscale di 16 caratteri

SIGN ES — Errori di validazione

SIGN ES restituisce gli errori di validazione in un array validations nella risposta, ognuno con un code e una description. Questi sono specifici per le trasmissioni TicketBAI / Verifactu / SII.

Codice di validazione	Causa
`V_TICKETBAI`	Errore sconosciuto o non gestito da TicketBAI
`V_XSD_SCHEMA_NOT_COMPLY`	Il file XML non è conforme allo schema XML
`V_INVOICE_WITHOUT_LINES`	Il file XML non include righe di dettaglio
`V_REQUIRED_FIELD_MISSING_OR_INCORRECT`	Dati obbligatori mancanti o errati
`V_INVOICE_ALREADY_REGISTERED`	Una fattura con lo stesso numero/serie/anno era già stata registrata
`V_SERVICE_NOT_AVAILABLE`	Il servizio di ricezione non è disponibile
`V_INCORRECT_SENDER_CERTIFICATE`	Il certificato del mittente è sconosciuto
`V_INVALID_SENDER_CERTIFICATE`	Il certificato del mittente non è valido
`V_WRONG_SIGNATURE`	La validazione della firma è fallita
`V_INCORRECT_INVOICE_CHAINING`	L’incatenamento delle fatture era errato
`V_INVALID_TBAI_LICENSE`	Licenza TicketBAI non registrata o non valida
`V_DEVICE_NOT_REGISTERED`	Il certificato del dispositivo usato per l’invio è in attesa di registrazione
`V_EXPIRED_SIGNATURE_CERTIFICATE`	Il certificato usato per firmare il file TicketBAI è scaduto
`V_EXPIRED_SENDER_CERTIFICATE`	Il certificato del mittente non è valido o è scaduto
`V_EXPIRED_SIGNER_CERTIFICATE`	Il certificato usato per la firma non è valido o è scaduto
`V_FULL_AMOUNT_MISMATCH`	La somma dei `full_amount` delle righe non è uguale al `full_amount` della fattura
`V_ISSUE_DATE_OUT_OF_RANGE`	La data di emissione è precedente a 20 anni o è nel futuro
`V_INVALID_VAT_RATE`	L’aliquota IVA non è un valore valido per la regione del contribuente
`V_INVOICE_ALREADY_CANCELLED`	La fattura era già stata annullata
`V_INVOICE_ALREADY_CORRECTED`	La fattura era già stata corretta
`V_INCOMPATIBLE_VAT_SYSTEMS`	I sistemi IVA forniti non sono compatibili tra loro
`V_INCORRECT_ITEM_VAT_CALCULATION`	Un articolo della fattura ha un calcolo IVA applicato in modo errato

📘Gli errori di validazione di SIGN ES non sono bloccanti

Gli errori di validazione compaiono nell’array validations della risposta ma non impediscono necessariamente la creazione del record. Controlla il campo state del record (REJECTED o FAILED) per determinare se l’errore è stato fatale.

Raccomandazioni sui timeout

Le diverse operazioni hanno durate attese diverse. Configura i tuoi timeout di conseguenza:

Operazione	Timeout consigliato	Note
Autenticazione (`POST /auth`)	3-4 secondi	Operazione rapida; non bloccare il checkout
Firma transazione (`PUT /tx`)	3-5 secondi	Non dovrebbe mai bloccare il POS
Creazione / inizializzazione TSS	30 secondi	Configurazione una tantum; elaborazione più pesante
Chiusure punto cassa DSFinV-K	Fino a 10 minuti	Elaborazione pesante con grandi dataset
Generazione esportazione	Basata su polling	Usa polling asincrono, non attesa sincrona

⚠️Non bloccare mai il checkout

Imposta i timeout di firma delle transazioni tra 3 e 5 secondi. Una firma mancante non rende una ricevuta non conforme (vedi AEAO al 146a, Punto 7). Aggiungi una nota come “TSS non disponibile” alle ricevute non firmate e includile nell’export DSFinV-K.

💡Rendi i timeout configurabili

Consenti agli amministratori di regolare i valori di timeout (es. 1,5-5 secondi per le transazioni) senza modifiche al codice. Questo risparmia cicli di sviluppo e si adatta a condizioni di rete variabili.

Strategia di retry

Per gli errori transitori (5xx, timeout, limiti di frequenza), usa il backoff esponenziale:

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const isRetryable =
        error.status >= 500 ||
        error.status === 429 ||
        error.code === "ETIMEDOUT";

      if (!isRetryable) throw error;

      const delay = Math.min(1000 * 2 ** attempt, 30000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Albero decisionale per la risoluzione dei problemi

Hai un errore?
  │
  ├── 401 Unauthorized
  │     └── Il tuo token è scaduto?
  │           ├── Sì → Ri-autenticati con chiave API + segreto
  │           └── No → Controlla le credenziali nell'HUB
  │
  ├── 400 Bad Request
  │     └── Controlla il campo `message` per sapere quale campo è non valido
  │           └── Valida il tuo payload JSON rispetto allo schema API
  │
  ├── 404 Not Found
  │     └── La risorsa esiste?
  │           ├── Controlla che l'ID sia corretto (formato UUIDv4)
  │           └── Assicurati che la risorsa sia stata creata nell'ambiente corretto (TEST vs LIVE)
  │
  ├── 409 Conflict
  │     └── La risorsa esiste già o è in corso di modifica
  │           └── Usa GET per controllare lo stato corrente prima di riprovare
  │
  ├── 429 Rate Limited
  │     └── Attendi con ritardo esponenziale
  │           └── Controlla se ti stai ri-autenticando ad ogni richiesta (non farlo)
  │
  └── Errore 5xx del server
        └── Controlla status.fiskaly.com
              ├── Incidente noto → Attendi la risoluzione
              └── Nessun incidente → Riprova con backoff esponenziale; contatta il supporto se persiste

Stato del servizio

Monitora lo stato del servizio fiskaly su status.fiskaly.com.

Errori comuni di integrazione

Questi sono gli errori che il supporto fiskaly vede più spesso dai team durante la loro prima integrazione. Evitarli fa risparmiare molto tempo di debug.

Errore	Cosa succede	Come evitarlo
Ri-autenticarsi ad ogni richiesta	Errori di limite di frequenza `429`; latenza non necessaria ad ogni checkout	Metti in cache l’access token (TTL 24h). Ri-autenticati solo con `401`.
Non salvare il `admin_puk`	Impossibile impostare il PIN Admin sul TSS; bloccato in stato `UNINITIALIZED`	Salva il `admin_puk` dalla risposta di creazione del TSS immediatamente.
Riutilizzare gli UUID	Errori `409 Conflict` quando si creano TSS, client o transazioni	Genera un nuovo UUIDv4 per ogni chiamata di creazione di risorse.
Bloccare il checkout su un fallimento di firma	I clienti aspettano indefinitamente se il TSS è lento o non disponibile	Imposta un timeout di 3-5 secondi sulla firma. Emetti la ricevuta con “TSS non disponibile” e riprova più tardi.
Usare credenziali TEST in LIVE (o viceversa)	`401 Unauthorized` — le credenziali sono specifiche dell’ambiente	Verifica che l’URL base corrisponda all’ambiente della chiave API. TEST e LIVE sono completamente separati.
Saltare l’inizializzazione del TSS	`400 E_TSS_NOT_INITIALIZED` quando si creano client o transazioni	Segui tutti i passi necessari: crea il TSS, aggiornalo a `UNINITIALIZED`, imposta il PIN Admin, accedi come Admin e imposta il TSS a `INITIALIZED`.
Non gestire correttamente `tx_revision`	`422 E_TX_INVALID_STATE` o errori di transazione duplicata	Inizia con `tx_revision=1` (ACTIVE), finisci con `tx_revision=2` (FINISHED). Incrementa sempre.
Polling sincrono delle esportazioni	Timeout nella generazione di esportazioni DSFinV-K (può richiedere fino a 10 minuti)	Usa polling asincrono: avvia l’esportazione, poi sonda l’endpoint di stato fino a `state: COMPLETED`.
Hardcodare i timeout	Il team di sviluppo non può regolarli senza un rilascio di codice	Rendi i timeout configurabili (es. 1,5-5 secondi per le transazioni). Regolabile dall’amministratore è l’ideale.

Risorse correlate

Guida alla gestione degli errori

Best practice per il timeout e il recupero degli errori in SIGN DE

Errori di dichiarazione

Codici di errore e codici di stato specifici di SUBMIT DE

Riferimento API

Documentazione completa degli endpoint per tutte le API fiskaly

Was this page helpful?