APIs Errors

About

The APIs will return a variety of errors if anything goes wrong with your API calls. Every error has an HTTP status code and, depending on the supported backend, will return an error type and brief explanation when the error is triggered. We expose API errors in JSON format. This documentation provides additional explanations of these errors and guidance on how to avoid them.

If your API call returns an error, log the call in as much detail as you can. If you need to contact our support, we recommend including the complete request you’re trying to make, the error code, and the response you’re receiving so they can help as quickly as possible.

Common causes

Here are some general troubleshooting steps for common IoT API error messages:

ErrorTroubleshooting
Unauthorized AccessDouble-check the authentication credentials you are using, such as API keys or access token, and ensure they are correct.
Invalid Request ParametersReview the API documentation to ensure you are using the correct request parameters and formatting them properly.
Resource Not Found:Verify that the requested resource or endpoint exists and is accessible.
Check if there are any typos or errors in the URL or resource identifier.
Rate Limit ExceededTry a new request after 1 hour.
Consider optimizing your API usage by batching requests or reducing the frequency of requests.
Server ErrorCheck our status page to see if there are any known issues with the API service.
Retry the request after some time as the server error may be temporary.
If the error persists, please contact our support team for further investigation.

For more detail, please consult:

Error repository:

HTTP 200 but the response is empty

Check that the request is properly formatted according to the API’s specifications.

Does the fields (filter for values)

  • contain invalid value
  • contain special char in value
  • has a white space after value
  • is not a string
  • is a string but with special chars

HTTP 400 Bad Request

There are different error titles returned for 400 errors, which will return an explanation in the “detail” field. Some of the most notable include:

Bad Request:

This is the generic error type for not being able to process the request, and will generally contain an explanation in the message.

Missing or malformed parameter:

The submitted POST body failed our input validation. This error may include an additional “errors” property, with a list of the validation issues.

Invalid Action:

The action requested was not valid for this resource.

Returned when you try to access an action on a resource that doesn’t support that action.

How to solve

  • Examine the response body and headers provided in the 400 error response.
  • Check that the request is properly formatted according to the API’s specifications.
    • pageSize and pageNumber must be valid numbers
  • Ensure that the HTTP headers, request method (e.g., GET, POST), and endpoint URL are correct.

HTTP 401 Unauthorized

Authentication information is missing or invalid.

How to solve:

  1. Go to Application Access Management
  2. Check the authentication credentials you are using, such as API keys or access token, and ensure they are correct.
  3. Verify that the credentials have the necessary permissions to access the requested resource.
  4. If using OAuth-based authentication, ensure that the authentication flow is correctly implemented and that you have obtained a valid access token.
  5. The access token expires every 5 minutes, you may need to generate a new token.

HTTP 403 Forbidden

Not enough permissions. The client has valid credentials but not enough privileges to perform an action on a resource.

How to solve:

Please contact the admin of your T IoT Hub tenant to update your access permissions.

Considerations per platform:

Similar to all supported platforms.

HTTP 404 Not Found

No data could be found by this request and it’s parameters.

How to solve:

  • Check the ID of the product. Is it valid or empty? Remove spaces before or behind the ID.
  • Is the filter valid? Is there a white space at the end of the filter? Is the filter a String?

HTTP 429 Too Many Requests

The HTTP 429 Too Many Requests response status code indicates the user has sent too many requests in a given amount of time (see rate limiting ).

How to solve:

  • Try to reduce the amount of requests, e.g. status changes can be done for multiple IDs in a single request
  • Use client side caching, so repeating calls can be avoided (e.g. in GUIs or reports)
  • Add wait or delays between requests or retries, i.e. in batch scripts with hundreds of calls.

HTTP 500 Internal Server Error

In general this appears in case of a non client or request related problem on server side, e.g. if the request to a backend platform runs into timeout conditions.

Unfortunately some CMO platforms also send back a 500, if the request is not valid or the credentials are unvalid or expired.

How to solve:

  • Check that the request is properly formatted according to the API’s specifications.
  • Check the authentication credentials in Application Access Management
  • Retry the request later (e.g. in case ob a backend platform overload).