Gestione degli errori

L'Amica Cloud API usa i codici di stato HTTP standard e, in caso di errore, restituisce un corpo conforme a RFC 7807 Problem Details, un formato JSON facilmente interpretabile da qualsiasi client.

Codici di stato

Codice	Significato
400	Bad Request — validazione fallita o parametro obbligatorio mancante.
401	Unauthorized — token mancante o scaduto.
403	Forbidden — accesso negato: vedi Cause del 403.
404	Not Found — la risorsa richiesta (o l'azienda indicata da companyId) non esiste.
405	Method Not Allowed — la risorsa è di sola lettura (es. giornalemagazzino).
409	Conflict — conflitto di concorrenza.
422	Unprocessable Entity — entità non processabile (es. token di concorrenza obsoleto).
429	Too Many Requests — superato il rate limit.

Cause del 403

Il corpo di un 403 è un Problem Details con un campo code che ne indica la causa, così il client può reagire nel modo giusto:

code	Causa
(assente)	Il token non possiede lo scope richiesto.
cloud_not_active	L'account non ha il servizio cloud attivo. Il valore è letto al rilascio del token: dopo l'attivazione serve un nuovo token.
company_license_not_active	La licenza dell'azienda indicata da companyId non è attiva. L'elenco delle aziende (config/Azienda) resta raggiungibile, così l'utente può passare a un'altra azienda.

Validazioni forzabili

Alcune risposte 400 includono un campo overridable che indica se l'errore di validazione può essere ignorato impostando il parametro validationOverride a true nella richiesta. È utile quando la tua integrazione deve poter salvare un dato che l'API segnala come anomalo ma che, nel tuo contesto, è accettabile.

Warning

Usa validationOverride con consapevolezza: forzando la validazione ti assumi la responsabilità della correttezza del dato. Forza solo gli errori che l'API marca esplicitamente come overridable.