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 |