Error handling

The Viously API follows RFC 7807. Every non‑2xx response therefore contains:

Field	Description
@context	Link to the JSON‑LD context for an error.
@type	The error type
hydra:title	Short, human‑readable summary.
hydra:description	Detailed explanation of what went wrong.
violations (optional)	Array of field‑level issues for 400 / 422 validation errors.

Example:

{
  "@context": "/v2/contexts/ConstraintViolationList",
  "@type": "ConstraintViolationList",
  "hydra:title": "An error occurred",
  "hydra:description": "hostname: The hostname must be a valid hostname.\nuser_network: The user network must not be null.",
  "violations": [
    {
      "propertyPath": "hostname",
      "message": "The hostname must be a valid hostname.",
      "code": "7057ffdb-0af4-4f7e-bd5e-e9acfa6d7a2d"
    },
    {
      "propertyPath": "user_network",
      "message": "The user network must not be null.",
      "code": "ad32d13f-c3d4-423b-909a-857b961eb720"
    }
  ]
}

HTTP Status Code

The Viously API uses standard HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error resulting from invalid provided information (e.g. a required parameter is missing, invalid access token, etc.), and codes in the 5xx range indicate an error with the Viously servers. More common errors codes are the following:

HTTP errors	Corresponding Viously error
400 Bad Request	The API call was invalid (e.g: using an invalid parameter).
401 Unauthorized	On `/authentication`, your authentication attempt failed. Elsewhere, a valid access token should be provided. This error may come from a missing or expired access token.
403 Forbidden	The request is understood, but it has been refused or access is not allowed. This code is used when the request requires higher privileges than provided by the access token.
404 Not Found	The requested object was not found (can also be thrown when you request deleted datas, non active users, etc.).
405 Method Not Allowed	Invalid HTTP Method. E.g : you call `/authentication` in `GET` instead of `POST`
422 Unprocessable Entity	Validation failed on the submitted data.
500 Internal Server Error	This API error covers any other type of problem (e.g: a temporary problem with the Viously servers) and should turn up only very infrequently.

Best Practices

Always inspect status and hydra:description to decide whether to retry or fix the request.
Handle 429 with retries, respect the Vsly-Rate-Reset header's value or use exponential back‑off.
For validation errors (422, iterate over the violations array to display precise messages to your users.
Log the full response body; it contains far more context than the numeric HTTP code alone.