Passa al contenuto principale

Errori & Troubleshooting

Questa sezione descrive come Homsai restituisce gli errori dalle API, quali codici HTTP vengono usati più spesso e come interpretarli lato client.

Overview​

Quando una richiesta non va a buon fine, il backend Homsai:

  • utilizza codici HTTP standard per distinguere errori client (4xx) da errori server (5xx);
  • restituisce un payload JSON strutturato con informazioni sull’errore;
  • usa messaggi tecnici ma leggibili per facilitare il debugging lato client.

In questa guida vedrai:

Struttura della risposta di errore​

Gli errori vengono restituiti in formato JSON con una struttura standard, ad esempio:

{
  "timestamp": "2025-12-12T10:45:22Z",
  "status": 403,
  "error": "Forbidden",
  "message": "Permission PLANTS READ required",
  "path": "/plants"
}

Campi principali:

  • timestamp: data e ora in cui si è verificato l’errore.
  • status: codice HTTP (es. 400, 401, 403, 404, 500).
  • error: descrizione sintetica del tipo di errore (es. Bad Request, Unauthorized, Forbidden).
  • message: dettaglio leggibile pensato per sviluppatori, che spiega il motivo dell’errore (permesso mancante, parametro non valido, ecc.).
  • path: endpoint invocato.

Lato client è buona pratica:

  • loggare l’intero payload di errore in ambienti di sviluppo;
  • mostrare all’utente finale messaggi derivati da message ma filtrati/contestualizzati.

Codici HTTP comuni​

400 – Bad Request​

La richiesta è formalmente errata o mancano parametri obbligatori.

Esempi:

  • body JSON non valido;
  • parametri startDate/endDate con formato errato;
  • valori fuori range per certi campi.

Cosa fare lato client:
correggere la richiesta (formato parametri, body) prima di riprovare.

401 – Unauthorized​

Il token JWT è mancante, scaduto o non valido.

Esempi:

  • header Authorization assente;
  • accessToken scaduto o con firma non valida.

Cosa fare lato client:

  • se disponibile un refreshToken, richiamare GET /auth/token per ottenere un nuovo access token;
  • altrimenti, ripetere il login (POST /auth/login).

403 – Forbidden​

Il token è valido, ma l’utente:

  • non ha i permessi necessari (es. manca PLANTS READ);
  • oppure non è owner del plant richiesto.

Cosa fare lato client:

  • verificare i ruoli/permessi dell’utente nell’interfaccia amministrativa;
  • mostrare un messaggio chiaro (“non hai i permessi per visualizzare questo impianto”).

404 – Not Found​

La risorsa richiesta non esiste o non è accessibile al chiamante.

Esempi:

  • plantUuid inesistente o non visibile all’utente;
  • deviceUuid o sensorUuid errati.

Cosa fare lato client:

  • controllare che gli ID utilizzati siano corretti;
  • gestire il caso “risorsa non trovata” nell’interfaccia utente (es. reindirizzare alla lista).

409 – Conflict​

Si verifica un conflitto di stato nel backend.

Esempi (a titolo indicativo):

  • tentativo di creare una risorsa con identificativo già esistente;
  • operazioni non consentite a causa di vincoli di dominio (es. cancellare un plant in uso da processi attivi).

Cosa fare lato client:

  • mostrare un messaggio che suggerisca di cambiare i dati o riprovare in un altro momento;
  • offrire azioni correttive (es. modificare un identificativo).

422 – Unprocessable Entity​

I dati sono sintatticamente corretti ma semanticamente non accettabili.

Esempi:

  • combinazione di parametri che non ha senso per il dominio (date invertite, plant non compatibile con certo tipo di sensore);
  • violazioni di regole di validazione più complesse.

Cosa fare lato client:

  • usare message per mostrare un feedback accurato;
  • validare quanto possibile i dati già lato front‑end.

500 – Internal Server Error​

Errore interno imprevisto lato server.

Non è imputabile alla richiesta (se ben formata): indica un problema infrastrutturale o un bug.

Cosa fare lato client:

  • mostrare un messaggio generico di errore temporaneo;
  • invitare l’utente a riprovare più tardi;
  • se l’errore è persistente, segnalarlo al supporto Homsai con dettagli (timestamp, path, status, message).

Casi tipici e come gestirli​

  • Token scaduto

    • Sintomi: 401 Unauthorized con messaggio che indica token non valido/scaduto.
    • Azione client:
      • usare refreshToken per ottenere nuovo accessToken;
      • in caso di fallimento, forzare nuovamente il login.

  • Permesso mancante

    • Sintomi: 403 Forbidden, messaggi tipo “Permission X required”.
    • Azione client:
      • nascondere o disabilitare funzioni non autorizzate nell’UI;
      • mostrare un messaggio chiaro senza dettagli tecnici superflui.

  • Plant non accessibile

    • Sintomi: 404 Not Found o 403 Forbidden per un certo plantUuid.
    • Azione client:
      • verificare che l’utente sia owner o abbia accesso a quel plant;
      • aggiornare la lista impianti mostrata lato UI.

  • Parametri data errati

    • Sintomi: 400 Bad Request con messaggi relativi a startDate, endDate o formato data.
    • Azione client:
      • applicare controlli di formato e range lato front‑end;
      • guidare l’utente nella selezione di date valide tramite date‑picker.

Una gestione coerente di questi casi nel client migliora notevolmente l’esperienza di integrazione e riduce il carico di supporto.