API Responses

 

The following responses are sent from the ITAS API:

  • 200 - OK.
  • 201 - OK, New resource created.
  • 400 - Bad Request - The request was invalid. The exact error should be explained in the error payload. e.g. Invalid Json, missing attributes.
  • 401 - Unauthorised - The request requires authentication.
  • 403 - Forbidden - The server understood the request, but is refusing it or the access is not allowed.
  • 404 - Not Found - The URI data is incorrect.
  • 500 - Internal Server Error - This error is not returned by the application but by the server.

 

The ITAS Response Envelope

All responses from ITAS API V2 endpoints are contained within a response envelope. This is a new feature of V2 and does not exist in V1. The Envelope contains four parts, each part is only sent in the response if it is populated:

  • Data - used for the body data e.g. a list of entities or details of a specific entity, or the id of an entity after it has been created. This can be either an array or an object depending on the endpoint called.
  • Pagination - when the response contains a list of entities, the pagination section includes meta-data associated with the list. Object.
  • Response - used to denote the response type e.g. success or failure. Always a string.
  • Messages - used to return error, warning and information messages. Array.

Example:

 

Pagination

The Pagination section of the response envelope describes the dataset returned in the Data part of the response envelope:

  • Total - total number of records in the dataset.
  • Top - how many records can be returned. The default is 200 and if there are more than 200 records in the available dataset only 200 will be returned by default. This can be overridden by adding a Limit value to the Odata querystring i.e. $limit=1000
  • Skip - the position of the first record to be returned from the dataset. i.e. $offset=100 will return records starting at position 101.
  • Returned - actual number of records returned.

The following pagination describes the records returned as: 146 records, starting at position 401, from a total or 547 records with a limit of 200. Note that the reason only 146 records are returned when 200 are requested is that the dataset finishes before the 200'th record is found.

 

Error Responses

Error responses are generally served as 400 Bad Request, the exact details can be found in the message payload. All responses follow the same format.

 

 

Where Messages are an array of Severity with SeverityMessageDetail and Message with ErrorMessageDetail. One of the several internal error messages is detailed below

 

Inner Error Message Codes

Detailed error messages are delivered as part of 400 and 404 responses and are sent in the following format

 

For example

 

Combining the Error Response and the Error Messages, the response will take the following format. Error Messages is an array which if expected will contain multiple Messages.

 

The table below shows a list of error messages and their codes.

Code Severity Full Description
API5054 Error  API5054 - Config : More than one MasterData Company is configured in the ITAS Heritage database which is not allowed. Please contact Hivedome support to check MasterData configuration
API5058 Error API5058 - Data : The mandatory field {fieldname} was missing in the request body
API5059 Error API5059 - Data : The value sent for the field {fieldname} exceeded the maximum number of allowed characters
API5060 Error API5060 - Data : The value sent for the field {fieldname} is of the wrong data type
API5061 Error  API5061 - Connection : Database connection error, please contact Hivedome Support to check configuration parameters
API5062 Error  API5062 - API : Body of the request has incorrect JSON format
API5063 Error  API5063 - API : Incorrect token role
API5064 Error  API5064 - API : Token Expired
API5065 Error  API5065 - API : Authorisation Error
API5066 Error  API5066 - API : Incorrect routing. There is an issue with the URI of the request made please check
API5067 Error  API5067 - API : The value {TradingEntityId} send as the TradingEntityId does not exist
API5068 Error API5068 - API : The value sent in the querystring variable {Property} is not allowed
API5069 Error API5069 - API : The value send in the querystring variable {PropertyValue} does not exist in the ITAS database for that Trading Entity
API5070 Error API5070 - API : Querystring variables {Property} and {PropertyValue} are dependant. Either send both or neither
API5071 Error API5071 - API : A value in the URI and the Body of the request do not match
API5072 Error  API5072 - API : There was an error with the body of the request
API5073 Error API5073 - API : Entity {EntityValue} passed in field {FieldValue} was not found for TradingEnity {TradingEntityId}
API5074 Warning API5074 - API : The value sent in the URI variable {Property} is not allowed
API5075 Warning API5075 - API : The combination of querystring parameters used do not return any records. Please amend or remove the querystring.
API5076 Error API5076 - API : The entity {EntityId} already exists for Trading Entity {TEID}. Creating another with the same ID is not allowed.
API5077 Error API5077 - API : API Method Not Allowed
API5078 Error API5077 - API : The code sent in parameter {0} could not be found. Sub objects must already exist before they can be used as part of a create or update request
API5080 Info API5080 - API : The fields [field x] and [field y] are not supported via a POST/PUT/PATCH will not be updated
API5081 Error API5081 - API : Message was not sent to the events server. Check server url
API5082 Error API5082 - API : At least one TEID (trading entity) is required
API5083 Error API5083 - API : Supplied date has incorrect format. Should be:  YYYYMMDD, yyyy-MM-dd hh:mm:ss, yyyy/MM/dd hh:mm:ss, yyyy-MM-dd hh:mm:ss tt zzz or yyyy-MM-dd
API5084 Error API5084 - API : LEG : - This error indicates that the error was generated by ITAS Heritage
API5090 Error API5090 - API : The value {value} is not allowed for the field {FieldName}
API5091 Error API5091 - API : The value {value} is not allowed for the field {FieldName}
API5092 Error API5092 - API : Body of the request contains both PromptMonth & PromptDate. Only one of these properties can be included as part of the request body.
API5119 Error API5119 - API : No files were included in the upload
API5120 Error  API5120 - API : Error loading AllowedDocmanFiles configuration
API5121 Error  API5121 - API : Files of type .xxx are not allowed 
API5122 Error API5122 - API : Mutliple files cannot be uploaded simultaneously
API5123 Error API5123 - API : Error saving the file to the filesystem
API5124 Error API5124 - API : Error associating meta data to the document