# Codici di errore

> Codici HTTP, formati del corpo degli errori e codici di dominio dell'API fiscale, con l'azione da intraprendere.

Pagina HTML: https://app.billyssw.it/documentazione/errors  
Indice della documentazione: https://app.billyssw.it/documentazione/index.md  
Tutta la documentazione in un file: https://app.billyssw.it/documentazione/full.md

## 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

```json
{
  "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

```json
{
  "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

```json
{
  "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. |