Once the Request code API processes the request, it will generate a response. An example of such a response:
{
"api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6",
"result_info": {
"status_code": 0,
"description": "Success"
},
"result": {
"message_id": "14466445287300014003"
}
}
All responses will come with the appropriate HTTP status code. Also an extra status_code is used to show the resolution of the request. Only when a request is successful the code will be 0 otherwise, if an error occurs it can be identified with its specific code.
Key | Type | Optional | Description |
---|---|---|---|
api_job_id | String | N | A unique identifier generated per request. This can be used to track a specific request. |
result_info | ResultInfo | N | Holds details about the resolution of the request. Always available. |
result | Result | Y | If available, holds the result to the request. |
Key | Type | Optional | Description |
---|---|---|---|
status_code | Integer | N | Holds a an integer value of the response status. i.e.:
0 = success, -50 = not authorized (Described in Section Error/Success Messages) |
description | String | N | Holds a text description of the response status. |
Key | Type | Optional | Description |
---|---|---|---|
message_id | String | N | The unique ID for the SMS message sent. |
Once the Validate code API processes the request, it will generate a response. An example of such a response:
{
"api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6"",
"result_info": {
"status_code": 0,
"description": "Valid"
}
}
All responses will come with the appropriate code. These are described in Section Error/Success Messages.
Key | Type | Optional | Description |
---|---|---|---|
api_job_id | String | N | A unique identifier generated per request. This can be used to track a specific request. |
result_info | Integer | N | Holds details about the resolution of the request. Always available. |
Key | Type | Optional | Description |
---|---|---|---|
status_code | Integer | N | Holds a an integer value of the response status. i.e.:
0 = success, -50 = not authorized (Described in Section Error/Success Messages) |
description | String | N | Holds a text description of the response status. |
When responding, the REST API will reply with an HTTP status, response code and a self explanatory message.
The following are the currently available messages.
Response Message | Response Code | HTTP Status | Description |
---|---|---|---|
Your authorization token is invalid. | -50 | 401 | When the Authorization token found in the header is not valid. |
Authorization token not provided. | -51 | 401 | When the Authorization token is missing from the header. |
Client ref provided already exists. Please provide a different one. | -52 | 422 | When requesting a new code and the client ref provided has already been used with the Authorization token provided. |
Invalid | -53 | 200 | When the code being validated has expired. |
Declined | -54 | 422 | When the code being validated cannot be found. i.e. it was incorrectly entered by the client. |
The code for the provided client ref. and authorization token, was not found. | -55 | 422 | The code provided does not match the authorization token and client_ref |
No code was provided. | -56 | 422 | The code was not provided in request. |
Code length too short. | -57 | 422 | When the code_length provided is smaller than the minimum. |
Code length too long. | -58 | 422 | When the code_length provided is bigger than the maximum. |
Phone number format is incorrect. | -59 | 422 | When format of the phone_number is not a valid mobile number. |
No phone number provided in request | -60 | 422 | When phone number is missing in the request body. |
Callback URL is invalid | -61 | 422 | When a non valid URL is provided as callback_url. |
No client ref provided in request | -62 | 422 | When no client_ref is provided in the request body. |
Sender ID is too long. Maximum numeric is 15 & maximum alphanumeric is 11. | -63 | 422 | When the sender_id provided in request body is bigger than 15 characters if numeric or is bigger than 11 characters if alphanumeric. |
System error – Request data provided was invalid. | -64 | 400 | When the request data is in a malformed manner or is not recognizable by the endpoint. |
Something went wrong. Make sure data provided is valid and please try again. | -65 | 400 | When an error occurred in the system’s back end due to system failure or due to some incorrect data provided. |
List of allowed IPs contains one or more invalid IP addresses. | -66 | 400 | When the list of IPs available with the authorization token has one or more IPs malformed. |
The request IP is not in your list of allowed IP addresses. | -67 | 400 | When request IP does not match any one form the list of allowed IP addresses available for the authorization token. |
Message template must contain placeholder {#TFA_CODE}. | -68 | 422 | When the message template is specified however it does not contain the required placeholder. |
Message template exceeds the length of one SMS. | -69 | 422 | When the total length of the message (message template + code) is longer than 1 SMS. |
Success | 0 | 201 | When the request for a new code has been completed successfully. |
Valid | 0 | 200 | When the code is valid. |
HTTP Status Code | Description |
---|---|
200 | All OK |
201 | Created OK. |
400 | Bad Request – The request is invalid and was not understood by the API. |
401 | Unauthorized – Header “Authorization” missing, invalid, or revoked; and/or, your host IP is not in the authorized IPs list. |
403 | The request contains invalid or illegal values. |
404 | Not Found – The endpoint on which the request was sent to, does not exist, or does not implement the API requested. |
405 | Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint. |
413 | Request entity was too large. Maximum size of X bytes allowed. |
415 | Unsupported Media Type – If the request was in a content-type not supported by the endpoint (ex. text/plain instead of application/json). |
422 | Unprocessable Entity – If a validation error occurs on the endpoint. |
429 | Too many requests (Throttling) |
500 | Internal Server Error |