Riferimento errori

I codici HTTP, il corpo JSON di ciascun tipo di errore e i codici di dominio restituiti dall'API fiscale.

Accept: application/json

Invia sempre l'header Accept: application/json.

Codici HTTP

Codice	Quando si verifica
200	Richiesta completata.
202	Richiesta accettata ed elaborata in modo asincrono (es. segnalazione di inattività).
400	Richiesta non elaborabile per un motivo diverso dalla validazione.
401	Access token assente, scaduto o non valido, oppure utente non abilitato su Billy.
403	Token valido ma operazione non consentita: scope non concesso o ruolo dell'utente insufficiente.
404	Risorsa inesistente. Anche un PEM che esiste ma non appartiene all'esercente del token risponde 404.
409	Operazione incompatibile con lo stato attuale: PEM non nello stato richiesto, Journal o documento in uno stato che non la consente.
422	Payload non valido (validazione) o dato rifiutato dalle regole fiscali.
429	Troppe richieste dallo stesso indirizzo IP: sul link pubblico al PDF del documento oltre 60 al minuto, sulla richiesta di registrazione dell'esercente oltre 5 al minuto o 20 all'ora.
500	Errore interno, non dipendente dalla richiesta.
502	Un servizio a valle (Punto di Elaborazione o identity provider) non ha risposto come atteso.

Autenticazione (401)

Il campo error dice cosa fare: rinnovare il token o ripetere l'autorizzazione dell'esercente.

401 · token scaduto

{
  "success": false,
  "message": "Il token di accesso è scaduto.",
  "error": "token_expired"
}

error	Significato	Azione
token_expired	Access token scaduto.	Rinnovarlo con il refresh token e ripetere la richiesta.
token_invalid	Firma, emittente, audience o claim obbligatori non validi.	Ottenere un nuovo token con il flusso di autorizzazione.
unauthenticated	Header Authorization assente, oppure l'utente del token non è abilitato su Billy. Questo corpo non ha il campo success.	Verificare l'header; se persiste, contattare il supporto Sender.

Accesso e stato del PEM (403, 404, 409)

HTTP	Corpo	Quando
403	{"success": false, "message": "Richiesta non autorizzata"}	Scope mancante, token di un utente che non è esercente né operatore, ruolo insufficiente per l'operazione.
404	{"success": false, "message": "Il PEM specificato non è stato trovato."}	Seriale inesistente o PEM di un altro esercente (per un operatore: un PEM diverso dal suo).
404	{"success": false, "message": "La risorsa richiesta non è stata trovata."}	Altra risorsa inesistente (richiesta, documento gestionale, rotta).
409	{"message": "Questa richiesta può essere elaborata solo da un PEM In servizio"}	Emissione, chiusura o cambio dell'opzione buoni pasto su un PEM non In servizio.

Validazione (422)

message riporta il primo errore, errors tutti, per campo. Le regole con un testo dedicato rispondono in italiano, le altre con il messaggio predefinito in inglese: basa la logica del client sulle chiavi di errors, non sul testo.

422 · validazione

{
  "success": false,
  "message": "La somma degli importi dei pagamenti è inferiore al totale da pagare",
  "errors": {
    "pagamenti": [
      "La somma degli importi dei pagamenti è inferiore al totale da pagare"
    ]
  }
}

Codici di dominio

Gli errori del dominio fiscale portano un codice stabile in error_code, senza il campo success. La tabella elenca quelli che un client può ricevere.

409 · codice di dominio

{
  "error_code": "JN002",
  "message": "Apertura effettuata da più di 24 ore (ID: 42, Data: 2026-10-07 08:00:00)"
}

Codice	HTTP	Significato e azione
JN001	409	Catena hash del Journal non valida. Contattare il supporto.
JN002	409	Giornata aperta da più di 24 ore: eseguire la chiusura di cassa prima di emettere.
JN003	404	Nessun Journal da chiudere.
JN004	502	Il PEL non ha aperto la nuova giornata durante l'emissione. Il documento non è emesso: riprovare con la stessa idempotency_key.
JN005	409	Documenti commerciali ancora in attesa di invio al PEL: riprovare la chiusura dopo qualche istante.
JN006	409	Chiusura già effettuata.
JN007 · JN008	409	Stato del Journal incoerente con l'operazione. Contattare il supporto.
JN009 · JN010	422	Journal non ancora chiuso, oppure chiuso ma non ancora inviato al PEL.
JN011	409	PEM già dismesso.
JN013	409	Numerazione dei DC esaurita: la giornata è stata chiusa d'ufficio. Ripetere l'emissione, che riparte da una nuova serie.
JN014	409	Numerazione dei Journal esaurita: il PEM è dismesso.
JN015	409	Cambio sede approvato: l'emissione è sospesa fino alla chiusura di cassa.
PL001	come il PEL	Il Punto di Elaborazione ha rifiutato la richiesta; message ne riporta il motivo.
XM001	422	Documento non conforme allo schema XML dell'AdE.
AE002	422	L'AdE ha restituito errori sulla richiesta; message riporta i codici della Code List AdE.
DC001	404	Documento commerciale, o riga del documento, non trovato.
DC002	409	Il documento indicato non è una vendita: non si può annullare.
DC003	409	Documento già annullato.
DC004	409	Annullo o reso di un documento di un altro dispositivo datato dopo l'attivazione del PEM.
DC005	409	Documento non valido per il reso.
DC006	409	Quantità resa superiore a quella ancora rendibile.
DC007	409	Le righe di servizio non sono ammesse al reso.
BP001	422	L'opzione buoni pasto si cambia solo a cassa chiusa: eseguire la chiusura e riprovare.