Error handling

Error structure

The LIVOI API uses a consistent JSON schema for errors, allowing clients to handle status codes, error messages, and detailed causes consistently.

The error response contains:

• status_code: HTTP status code as a string
• status_message: HTTP status description, such as Forbidden or Unprocessable Entity
• errors: a list of error objects

An error object may contain these optional fields:

• info
• type
• context
• cause

cause can be a single object or a list. Validation errors typically produce a list. Cause entries may contain details, value, location, and code.

Minimal example

{
  "status_code": "403",
  "status_message": "Forbidden",
  "errors": [
    {
      "info": "Missing permission for agents.read."
    }
  ]
}

Validation errors

HTTP 422 is common for Pydantic field validation and Dynamic Query. The current status phrase is Unprocessable Entity.

{
  "status_code": "422",
  "status_message": "Unprocessable Entity",
  "errors": [
    {
      "info": "Validation failed.",
      "type": "ValidationError",
      "cause": [
        {
          "details": "Input should be greater than or equal to 1",
          "value": 0,
          "location": ["body", "page", "number"],
          "code": "greater_than_equal"
        }
      ]
    }
  ]
}

HTTP status codes

2xx Success

Code	Status	Description
200	OK	Standard response for successful HTTP requests. The resource was retrieved or processed successfully.
201	Created	The request succeeded and a new resource was created. Typically used for POST requests.
204	No Content	The request succeeded with no content to return. Common for DELETE operations.

4xx Client errors

Code	Status	Description
400	Bad Request	The request was invalid or incomplete. Check parameters, filters, and JSON formatting.
401	Unauthorized	Required authentication failed or was not provided.
403	Forbidden	Access to the resource was denied, for example because of missing permissions.
404	Not Found	The requested resource could not be found.
409	Conflict	The request conflicts with the current state of the resource.
422	Unprocessable Entity	The request could be parsed but contains semantic errors or invalid fields.
429	Too Many Requests	The client sent too many requests in a short period.

5xx Server errors

Code	Status	Description
500	Internal Server Error	An unexpected server error occurred.
503	Service Unavailable	The server is temporarily unavailable, for example due to maintenance or overload.

Dynamic Query route specifications include 400, 401, 403, 404, 422, and 500.