Skip to main content

Errors & Troubleshooting

This section describes how Homsai returns API errors, which HTTP codes are commonly used, and how to handle them on the client side.

Overview​

When a request fails, the Homsai backend:

  • uses standard HTTP codes to distinguish client errors (4xx) from server errors (5xx);
  • returns a structured JSON error payload;
  • provides technical but readable messages to help with client‑side debugging.

In this guide you will see:

Error response structure​

Errors are returned as JSON with a standard structure, for example:

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

Main fields​

  • timestamp: date and time when the error occurred.
  • status: HTTP status code (e.g. 400, 401, 403, 404, 500).
  • error: short description of the error type (e.g. Bad Request, Unauthorized, Forbidden).
  • message: human‑readable, developer‑oriented detail explaining the reason (missing permission, invalid parameter, etc.).
  • path: the endpoint that was called.

On the client side, it is good practice to:

  • log the full error payload in development environments;
  • show end users messages derived from message, filtered and adapted to the UI context.

Common HTTP status codes​

400 – Bad Request​

The request is syntactically incorrect or required parameters are missing.

Examples:

  • invalid JSON body;
  • startDate/endDate parameters with wrong format;
  • out‑of‑range values for some fields.

Client action: fix the request (parameter formats, body) before retrying.

401 – Unauthorized​

The JWT token is missing, expired or invalid.

Examples:

  • missing Authorization header;
  • expired or invalid accessToken.

Client action:

  • if a refreshToken is available, call GET /auth/token to obtain a new access token;
  • otherwise, repeat the login flow (POST /auth/login).

403 – Forbidden​

The token is valid, but the user:

  • does not have the required permissions (e.g. missing PLANTS READ);
  • or is not the owner of the requested plant.

Client action:

  • check the user’s roles/permissions in the admin interface;
  • show a clear message (e.g. “you are not allowed to view this plant”).

404 – Not Found​

The requested resource does not exist or is not accessible to the caller.

Examples:

  • plantUuid does not exist or is not visible to the user;
  • wrong deviceUuid or sensorUuid.

Client action:

  • verify that the IDs used are correct;
  • handle the “resource not found” case in the UI (e.g. redirect back to the list).

409 – Conflict​

A state conflict occurred in the backend.

Examples (indicative):

  • trying to create a resource with an identifier that already exists;
  • operations not allowed due to domain constraints (e.g. deleting a plant still used by active processes).

Client action:

  • show a message suggesting to adjust the data or try again later;
  • offer corrective actions (e.g. change an identifier).

422 – Unprocessable Entity​

The data is syntactically correct but semantically invalid.

Examples:

  • parameter combinations that don’t make sense in the domain (inverted dates, plant not compatible with a certain sensor type);
  • violations of more complex validation rules.

Client action:

  • use the message field to show accurate feedback;
  • validate as much as possible on the front end before sending the request.

500 – Internal Server Error​

Unexpected internal server error.

It is not caused by a well‑formed request; it indicates an infrastructure issue or a bug.

Client action:

  • display a generic temporary error message;
  • ask the user to retry later;
  • if the error persists, report it to Homsai support with details (timestamp, path, status, message).

Typical scenarios and how to handle them​

  • Expired token

    • Symptoms: 401 Unauthorized with a message indicating an invalid/expired token.
    • Client action:
      • use refreshToken to obtain a new accessToken;
      • if that fails, force the user to log in again.

  • Missing permission

    • Symptoms: 403 Forbidden, messages like “Permission X required”.
    • Client action:
      • hide or disable unauthorized features in the UI;
      • show a clear message without unnecessary low‑level technical details.

  • Plant not accessible

    • Symptoms: 404 Not Found or 403 Forbidden for a given plantUuid.
    • Client action:
      • verify that the user is the owner or has access to that plant;
      • refresh the plant list displayed in the UI.

  • Invalid date parameters

    • Symptoms: 400 Bad Request with messages referring to startDate, endDate or date format.
    • Client action:
      • apply format and range checks on the front end;
      • guide the user with proper date‑pickers and input constraints.

Consistent handling of these scenarios on the client side significantly improves the integration experience and reduces support workload.