Validаtion. Status codes for request processing

VMS employs standard HTTP status codes to indicate whether a request was successful or if an error occurred. This section of the documentation describes the standard HTTP response codes that the VMS API uses to communicate the status of request processing, along with examples of error responses.

HTTP status codes

If a request is successful, the server sends the client the OK status, identified by a 2xx code.

When an operation encounters an error, the server responds with a message describing the issue and an appropriate 4xx or 5xx status code.

2xx range codes	Status codes in the 2xx range signify successful completion of the request.
200, 201, 204 – OK	Successful completion of the request.
4xx codes	Status codes in the 4xx range denote an error in the request, caused by insufficient or invalid input (e.g., a required parameter wasn’t provided).
400 – Bad Request	The request failed due to incorrect input or external system issues.
402 – Payment Required	The license limit for creating cameras is exceeded, or there is a license issue.
422 – Unprocessable Entity	The server understood the request, but couldn't process the data because it was invalid.
403 – Forbidden	No permissions to access the resource. For details, refer to Manage access to API. Authentication.
404 – Not Found	The requested resource isn’t found.
429 – Too Many Requests	An excessive number of requests are being sent to the API in a short period of time.
5xx codes	Status codes in the 5xx range denote technical errors that are rarely encountered. These errors are often associated with VSaaS servers.
500, 502 – Server Errors	Rarely encountered. These errors are typically associated with VSaaS servers.
503 – Service unavailable	System maintenance is in progress. This may involve system updates or troubleshooting.

Validation of the request with an error

When an operation fails, the server sends the client an error message along with an HTTP status code. These codes indicate whether the issue is client-related (400-499) or server-related (500-599).

The API generally provides error messages in a predefined format; however, alternative structures may be employed based on the nature of the request.

JSON

{
    "message": "No error message here",
    "errors": {
        "any_key": [
            "Error details"
        ]
    }
}

the message object – while the message object usually remains empty and doesn't hold error information, there are exceptions. For instance, with an error code of 400, it might include an error description.
the errors object – details issues encountered during a request. Its keys highlight problematic request fields, though errors can also arise independently of specific fields. The errorsobject can contain multiple errors.

Example

The request includes the url field set to http//example.com. This field has a validation rule requiring it to be a valid URL and no longer than 10 characters. There's also the date field with the value 2000-01-01, which needs to follow the Y-m-d H:i:s format.

The response for this request will be as follows:

{
    "message": "Submitted data was invalid",
    "errors": {
        "url": [
            "The URL value is in invalid format",
            "The URL can be no longer than 10 characters"
        ],
        "date": [
            "The date field doesn't match the format: Y-m-d H:i:s."
        ]
    }
}