An API response is a standard HTTP response containing a JSON object in the body.

Response Status Codes

Depending on whether the request has been successfully processed by the API server, the corresponding response may have one of the following HTTP status codes:

CodeMeaningDescription
200 Request was understood and processed The API Server understood the request and processed it successfully. Syntax of the request was fine.
400 Request was not understood Something is wrong with the request syntax. The API Server doesn't understand the request and hence cannot process it.
401 Missing or invalid client credentials The request cannot be processed because of missing/invalid client credentials.
403 Operation not permitted The client attempted to access an endpoint or an item without having sufficient permissions to do that.
404 Non-existing endpoint or item The client attempted to access an endpoint or an item that doesn't exist or that it doesn't have access to.
405 Request method is not allowed The client attempted to send a request of type that the endpoint in question doesn't support.
422 Request was not processed due to client error The request syntax was fine, but the content of the request included some invalid data that prevented the API Server from successfully processing it.
500 Request was not processed due to API error The API Server understood the request, but wasn't able to process it because of an unexpected error.

Response Types

The response object will always have a result property indicating whether the request has been processed and if the processing has been successful. Possible values of the property are:

ValueRequest TypeDescription
success

GET requests

Other requests

The request has been processed successfully.

All incoming items from the request body have been processed and saved successfully.
failure

GET requests

Other requests

Not applicable.

Some or all incoming items have caused processing errors. No items have been saved.
error All requests

The request has not been processed due to a fatal error.

Response Structure

If the request has been processed successfully, or – in case of non-GET requests – if all items from the request body have been processed successfully, then the response object will contain a collection of processed items. It will also include a metadata object (described below).

If some or all items from the request body have caused processing errors, then the response body will contain a failures collection with invalid items (described below).

If the request has not been processed due to a fatal error, then the response object will contain an error item (described below).

Metadata Object

The metadata object describes the response and may include various properties, depending on the request and response parameters.

PropertyData TypePresenceDescription
page Integer In response to GET requests Current page number.
pagesCount Integer In response to GET requests Total number of pages.
recordsPerPage Integer In response to GET requests Maximum number of records per each page.
recordsCount Integer In response to GET request Total number of records available.
receivedItemsCount Integer In response to POST, PATCH, and DELETE requests Total number of items received.
validItems List In response to POST, PATCH, and DELETE requests List of indices of valid items found in the request collection (if any).
invalidItems List In response to POST, PATCH, and DELETE requests List of indices of invalid items found in the request collection (if any).

Failures Collection

A failures collection contains items that cannot be processed correctly. These items can be mapped to the corresponding items from the original request collection by using indices from the invalidItems list of the response metadata object.

PropertyData TypePresenceDescription
rawData Object Always present Raw item data as the API understands it.
errors Collection Always present An array of error objects.

Error Object

An error object contains detailed information about the error and may also contain some hints for developers describing how the error can be avoided.

PropertyData TypePresenceDescription
type String Always present One of the following types: system, client, syntax, content, permission, validation.
code Integer Always present Error code.
message String Always present Error message.
description String May be present Verbose error description for developers (if available).
field String May be present in validation errors Name of the field whose value caused validation to fail.