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 Content-Type header of your request is valid.
- 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.
- Check that you have formatted and copied the access key correctly.
- Make sure the auth header contains the "Bearer" authorization scheme.

401 auth_mismatch Authentication failure: provided authorization header is not allowed for this request.
401 invalid_apikey Authentication failure: provided access key is invalid.
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 (for instance, that you called /v3/devices/ and not /v3/device/).
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.
409 conflict The request could not be completed due to conflicting current state.
409 duplicate The request would create a duplicate entity. This name is already in use. Please enter a different name for the \{resource\}.
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.