Error handling

The API returns 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:

1
{
2
  "error_code" :  1104,
3
  "error_token": "Forbidden",
4
  "message": "You do not have the necessary permissions to access this entry point. Please contact your administrator."
5
}

400 error codes come with a consumable JSON error representation:

1
{
2
  "error_code" : 1406,
3
  "error_token" : "NotAllowed",
4
  "message" : "Updating of own organisation not allowed.",
5
}

Some error codes like ValidationFailed can contain multiple error messages embedded:

1
{
2
  "error_code" : 1400,
3
  "error_token" : "InputValidationFailed",
4
  "message" : "Input validation failed",
5
  "errors" : [
6
    {
7
      "error_code" : 1403,
8
      "error_token" : "InvalidFormat",
9
      "message" : "User - Username has invalid format: expecting String."
10
    },
11
    {
12
      "error_code" : 1402,
13
      "error_token" : "Required",
14
      "message" : "User - organisation is required."
15
    }
16
  ]
17
}

List of error codes

Generic error codes

There are several error categories that have general applicability within API and aren’t specific to any particular resource.

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 isn’t registered in the HLR. This can occur if the IMSI doesn’t belong to emnify, the IMSI isn’t assigned to any SIM, the SIM isn’t 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 (that is, no location information is present in the HLR; this can occur if the IMSI is detached or didn’t respond to paging).

External Network Error
This error is used when the source of the error is external to the system, for example, 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, for example, 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 causes the following error:

1
409 Conflict

1
{
2
  "error_code" : 2101,
3
  "error_token" : "UnableToActivate",
4
  "message" : "Unable to activate",
5
  "description" : "No SIM."
6
}

Resource specific errors are segmented as follows: