All API response takes the general structure visualized below;
The general structure of any response has 3 main sections; status, data and errors.
1. The status section determines whether or not the response is a success. All success responses will have the status 1, all failures will have status codes less than -1 eg -2, -3 -4 etc. A remark will have a general description of the status code eg "Success" for status code 1 or any other general error message for status codes < -1.
2. The data section contains the payload when status code is 1 (success) and the invoked method has data that needs to be sent to the client. If the API method has no data to send or status code is < -1 (failure), this will be null.
3. The errors section contains an array of specific business errors when status code is < -1. Each element in the array has error code, fieldname and error message as shown in the structure below;
"errors": [
{
"errorCode": -20,
"fieldName": "transactionDate",
"errorMessage": "Transaction date can not be a future date"
}
]
If the status code of the response is 1 (success) then errors is always set to an empty array []. Typically, the terminal can get the general error from the remark field of the status section as it summarizes all details found in the errors section. For instance, if one or more mandatory fields in the request are missing, the status code may be set to -2 and remark may read "one or more mandatory fields are missing". The errors section will contain an array with details of all fields that are missing. It is correct to say that when status code is < -1 (failure), a remark from status section will always be available however the errors section may still be empty. An example of this is a scenario where the API has failed to connect to a database server and the request is valid. To report this error, the response will have a negative status code and Remark may be "Server error while connecting to the database". Since this is an internal server error and the payload is valid, the errors section will be an empty array.
USE OF HTTP STATUS CODES
Generally, the responses will be accompanied with HTTP status code eg 200 OK is always used when status code is 1 while other HTTP status code such as 401, 500 may be used in combination with status codes < -1.
