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 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 EMnify, 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