Errori

Formato uniforme, messaggi in lingua italiana, codici stabili.

Il formato

Ogni errore ha la stessa forma, con lo status HTTP giusto e un messaggio in lingua piana:

{
  "errore": {
    "codice": "riga_non_valida",
    "messaggio": "Riga 2: ART-9 ha delle varianti: indicare la variante."
  }
}

Gli status

Status	Quando
`400`	La richiesta è malformata: corpo non JSON, troppe chiavi in una lista.
`401` / `403`	Chiave assente, non valida, o senza il permesso — vedi Autenticazione.
`404`	La risorsa non esiste.
`409`	Conflitto: una chiave che identifica più di un record (`chiave_ambigua`), o una Idempotency-Key riusata con un corpo diverso.
`422`	La richiesta è ben formata ma le regole del gestionale la rifiutano: sono gli errori da presentare all'utente dell'integrazione.
`429`	Ritmo troppo alto — vedi Limiti.

I 422 principali

Codice	Significato
`filtro_non_valido`	Un filtro di elenco è presente ma non interpretabile (per esempio una data scritta male). Il filtro non viene mai ignorato: la richiesta va corretta e ripetuta.
`riga_non_valida`	Una riga di una scrittura «tutto o niente» è stata rifiutata: il messaggio dice quale e perché. Niente è stato scritto.
`fido_superato`, `sezionale_non_pronto`, `documento_rifiutato`	Le regole dei documenti: cliente oltre il fido, sezionale senza contatore, date bloccate dall'inventario.
`movimento_rifiutato`, `arrivo_rifiutato`, `allineamento_rifiutato`	Le regole del magazzino: lotto mancante su un articolo a lotti, quantità oltre l'ordinato, variante che non appartiene all'articolo…

I codici specifici di ogni endpoint sono nella reference.

Nelle scritture a esiti per riga (movimenti, arrivi) una riga rifiutata non butta le altre: il rifiuto sta nell'esito della singola riga, con lo stesso messaggio. Nei documenti invece vale il tutto o niente.