Documentation

Mistake on this page? Email us

Troubleshooting the APIs

This page explains how to decode and recover from errors when using the Device Management APIs.

Status codes and errors

If something unexpected happens when you're using the APIs, the most useful information is the HTTP status code. There are codes for successful operations as well.

The server returns success or failure information for a request using status codes, which are grouped by type:

  • 200 range: Success.
  • 300 range: Further action is required by the caller (you or the device).
  • 400 range: Errors due to request input.
  • 500 range: Errors on the Device Management servers.

Typical status and error code model

Status and error codes look like:

{
    "object": "error",
    "code": "<error_code>",  // HTTP status code, for example, 400.
    "type": "<error_type>",  // For example, "validation_error".
    "message": "A human-readable message with detailed info",
    "fields": [
        {
            "name": "<field_name>",
            "message": "A human-readable validation error"
        }
    ],
    "request_id": "<request_id>" // As assigned for the incoming request.
}

General error codes and types

The following is a description of some general HTTP error codes, along with what they mean in the context of Device Management. Most APIs also provide a list of specific error codes for each interface in the documentation.

Code Type Description Troubleshooting
400 bad_request Something is wrong with the request. * Check that the URL is valid and spelled correctly (for instance, that you called /v3/devices and not /v3/device/.
* Check that the interface is supported by the API you're calling.
400 validation_error One of the parameters is invalid. * Check that you have included all parameters required by the interface.
* Check that you have formatted parameters and values correctly in your request.
401 invalid_auth Authentication failure: provided authorization header is invalid. * Check that your request includes an authorization header.
* Sign in again.
* Check that you have formatted and copied the authorization token correctly.

401 auth_mismatch Authentication failure: provided authorization header is not allowed for this request.
401 invalid_token Authentication failure: provided token is invalid. * Sign in again.
* Generate a new authorization token if the old one might have expired.
401 invalid_apikey Authentication failure: provided API key is invalid. * Sign in again.
403 access_denied Authenticated user is not authorized to access the resource or execute the request. * Contact your administrator to check your user policy. Your access may be restricted depending on your location.
403 access_restricted Access was blocked to comply with export control.
403 account_limit_exceeded The account limit has been reached. * Your account type determines the number of operations you can carry out. Check your billing policy.
403 invalid_request Trying to access using HTTP instead of HTTPS. * Check that the URL of your request uses HTTPS instead of HTTP. You should always carry out API operations over a secure connection.
404 not_found Resource was not found. * The interface or resource doesn't exist.
404 unrecognized_request Unrecognized request URL, or method not supported by the API. * Check the spelling of your request URL.
405 method_not_supported Specified method is not supported by the API. * Check that the method you're calling is supported by the API.
* Check that you've spelled the URL correctly.
500 internal_server_error Unexpected internal server error. * Try the request again. If you have continued problems with the server, contact Pelion support.
503 system_unavailable System unavailable. * Try the request again. If you have continued problems with the server, contact Pelion support.