Responses and errors

Every request to the Netvisor API gets a standard XML response. This page describes the general structure of responses and the error categories that the API returns.

Response structure

The Root element always contains one ResponseStatus element, which contains these elements:

  • Status (string): Tells if the request succeeded. The value is OK or FAILED.

  • Status (string, second occurrence): The error type and description. This element is included only when the status is FAILED. See Controlling errors.

  • TimeStamp (date): The time of the response, for example 01.01.2018 12:00:00.

The rest of the response depends on the direction of the data transfer.

Retrieving data (GET)

The response contains the data you requested in a resource-specific element. Each resource description describes this element.

<Root>
<ResponseStatus>
<Status>OK</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
<!-- Resource-specific element with the requested data -->
</Root>

Importing data (POST)

Depending on the resource, the response can include one Replies element. It contains InsertedDataIdentifier or Reply elements, which can occur any number of times. For example, InsertedDataIdentifier contains the ID of the added item.

<Root>
<ResponseStatus>
<Status>OK</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
<Replies>
<InsertedDataIdentifier>1802</InsertedDataIdentifier>
</Replies>
</Root>

Error responses

If an error occurs, the ResponseStatus element contains <Status>FAILED</Status>. The second Status element contains the error type and description.

Example of a response to an incorrect request:

<Root>
<ResponseStatus>
<Status>FAILED</Status>
<Status>AUTHENTICATION_FAILED :: Integration keys are not valid. Please check the user- and partner-specific keys</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
</Root>

Error categories

  • AUTHENTICATION_FAILED: Authentication failed. Check the authentication information, the HTTP headers and the MAC calculation.

  • INVALID_DATA, INVALID_DATA_SIZE: The data is incorrect or the wrong size. Check the data and the parameters.

  • DUPLICATE_DATA: The data already exists in Netvisor. Check the data and the parameters.

  • REQUEST_NOT_UNIQUE: The unique identifier of the request has already been used. Use a new identifier in every request.

  • PERIOD_LOCK: The accounting period is locked. You cannot import data to it.

  • SERVICE_ACCESS_ERROR: There are no access rights, or the application that the data belongs to is not in use.

  • SYSTEM_MAINTENANCE: Netvisor is under maintenance. You cannot send requests during the maintenance break.

  • TECHNICAL_ERROR: Another technical error occurred. The response gives only the error category and a unique identifier, without a detailed description. Technical errors are logged. Partner support and maintenance can use the unique identifier to investigate the error later.

For detailed error messages, see Controlling errors.

Powered by DeveloperHub
On This Page
Responses and errorsResponse structureRetrieving data (GET)Importing data (POST)Error responsesError categories