Guida alla gestione degli errori

Consiglio

Ultimo aggiornamento il 2026-04-20.

La guida allegata fornisce una panoramica degli errori più comuni che si verificano durante l’invio di record tramite SIGN IT lite e di come risolverli. Tratta gli errori restituiti dall’endpoint POST /records (invio dei record), inclusi sia problemi a livello HTTP sia errori a livello applicativo.

Come identificare l’errore?

Controlla il campo logs nella risposta dell’API. Esempio:

{
  "state": "FAILED",
  "logs": [
    {
      "severity": "ERROR",
      "message": "Authentication error: ADE portal has not responded successfully"
    }
  ]
}

Il prefisso del messaggio di errore (ad esempio Authentication error, Validation error, Submission error, etc.) determina la categoria dell’errore.

Categoria	Significato	Retry?
Safe to retry*	Il documento commerciale non è stato trasmesso all’AdE perché l’errore si è verificato prima che raggiungesse l’endpoint di invio all’AdE.	Sì, con una nuova idempotency key
Requires verification	Il documento commerciale potrebbe essere stato trasmesso all’AdE poiché l’errore si è verificato durante o dopo il tentativo di invio all’AdE.	Verificare prima sul portale AdE. Se il documento commerciale non è presente, riprovare con una nuova idempotency key
In caso di errori sconosciuti o errore HTTP 500, inviare un’email a dev-support@fiskaly.com
includendo dettagli sufficienti per permetterci di indagare e fornire indicazioni sui passaggi successivi.

L’errore HTTP 503 viene restituito in caso di indisponibilità temporanea dell’infrastruttura. È sempre possibile riprovare utilizzando una nuova idempotency key. Se l’errore persiste per più di 1–2 minuti, l’infrastruttura potrebbe essere sotto carico prolungato; in quel caso, registra la transazione nel registro di emergenza e contatta dev-support@fiskaly.com.

*Nota di conformità: Le transazioni fiscali devono essere trasmesse in tempo reale. Ritardi o tentativi di ritrasmissione possono comportare rischi di non conformità e potrebbero non soddisfare i requisiti normativi.

fiskaly fornisce strumenti tecnici, ma non garantisce la conformità, che rimane responsabilità del cliente. Qualsiasi processo di ritrasmissione o recupero deve rispettare i tempi consentiti dalla legge e le normative locali. Per ulteriori dettagli, consultare la guida.  Nota: Alcuni prefissi di errore — in particolare Entity validation error e fiscalization invalid — possono verificarsi anche durante la fase in cui lo stato del Taxpayer viene aggiornato a COMMISSIONED. In quel caso, la risoluzione è più semplice: aggiorna i dati del Taxpayer in base al messaggio di errore ricevuto e riprova a impostare lo stato della risorsa su COMMISSIONED.