Error Handling

The API will return HTTP error codes according to the type of the error, 400 error codes are used for client related issues, 500 error codes for server side issue.

JSON error representation

403 status code is 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}

General errors are defined in this section and are not repeated throughout the specification.

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