Error Handling
The API will return HTTP error codes according to the type of the error;
400
error codes are used for client related issues500
error codes indicate server side issues
JSON error representation
403
status codes are returned with the following JSON error:
{
"error_code" : 1104,
"error_token": "Forbidden",
"message": "You do not have the necessary permissions to access this entry point. Please contact your administrator."
}
400
error codes come with a consumable JSON error representation:
{
"error_code" : 1406,
"error_token" : "NotAllowed",
"message" : "Updating of own organisation not allowed.",
}
Some error codes like ValidationFailed
can contain multiple error messages embedded
{
"error_code" : 1400,
"error_token" : "InputValidationFailed",
"message" : "Input validation failed",
"errors" : [
{
"error_code" : 1403,
"error_token" : "InvalidFormat",
"message" : "User - Username has invalid format: expecting String."
},
{
"error_code" : 1402,
"error_token" : "Required",
"message" : "User - organisation is required."
}
]
}
List of Error Codes
Generic Error Codes
There are several error categories that have general applicability within API and are not specific to any particular resource.
Category | HTTP Status | Error Code | Error Token | Description and parameters |
---|---|---|---|---|
Authentication | 401 | 1101 | InvalidCredentials | |
Authentication | 401 | 1102 | InvalidToken | |
Authentication | 401 | 1103 | TokenExpired | |
Authentication | 403 | 1104 | Forbidden | |
Authentication | 429 | 1105 | TooManyRequests | |
Navigation | 404 | 1201 | NotFound | {resource} with id {id} not found |
Paging | 422 | 1301 | InvalidQueryCriteria | Search criteria {criteria} is invalid |
Paging | 422 | 1302 | InvalidSortCriteria | Sort criteria {criteria} is invalid |
Validation | 422 | 1400 | InputValidationFailed | |
Validation | 422 | 1401 | InvalidReference | Invalid reference to {resource} with id {id} |
Validation | 422 | 1402 | Required | {Object} - {field} is required |
Validation | 422 | 1403 | InvalidFormat | {Object} - {field} has invalid format: Expecting {String/Number/Object} |
Validation | 422 | 1404 | OutOfRange | {Object} - {field} out of range ({range}) |
Validation | 409 | 1405 | Duplicated | {Object} - {field} already exists |
Validation | 400 | 1406 | NotAllowed | {Action} not allowed |
Validation | 409 | 1407 | CannotBeDeleted | {Object} still referenced |
Validation | 422 | 1408 | InvalidValue | {Object} - {field} is invalid: {value} |
Validation | 422 | 1409 | UnknownProperty | Unknown Property: {property} |
Rate Limit | 429 | 1501 | TooManyRequests | Too many requests |
Unavailable | 404 | 1601 | Unavailable | No {resource} available |
Connectivity | 404 | 1901 | UnknownSubscriber | Unknown Subscriber for Endpoint with id {id}* |
Connectivity | 404 | 1904 | UnknownLocation | Unknown Location for Endpoint with id {id}* |
Connectivity Errors
This section provides additional information about endpoint connectivity errors with HTTP 404
status codes are returned.
Unknown Subscriber Error:
This error indicates that the subscriber is not registered in the HLR. This can occur if the IMSI does not belong to BICS, the IMSI is not assigned to any SIM, the SIM is not activated or is suspended, etc.
Unknown Location Error
This error is used when the service request is made for a subscriber without valid location data (i.e. no location information is present in the HLR; this can occur if the IMSI is detached or did not respond to paging).
External Network Error
This error is used when the source of the error is external to the system, e.g. timeout on a Network Request towards VPLMN.
Network Element Not Available Error
This error indicates no network element available to process the service request.
Data Missing
An example of missing data would be a missing optional parameter required by the context.
Unexpected Data Value
Invalid data, e.g. an invalid MSISDN or IMSI.
Resource Specific Errors
Errors that are specific to a particular resource and operation being performed are described in resource section.
Most of the errors in this category return 409 Conflict HTTP status code.
For example, trying to activate an endpoint that has no SIM card associated will cause the following error:
409 Conflict
{
"error_code" : 2101,
"error_token" : "UnableToActivate",
"message" : "Unable to activate",
"description" : "No SIM."
}
Error specific errors are segmented as follows:
Code Range | Resource |
---|---|
2100-2199 | Endpoint |
2200-2299 | SIM |
2300-2399 | Service profiles |
2400-2499 | Traffic limits |
2500-2599 | User |
2600-2699 | Tariff |