The m3ter platform supports two APIs:
The Config API, which you can use for configuration requests and management.
The Ingest API, which you can use for submitting raw data measurements.
Error messages are returned for any invalid or incomplete calls made to these two APIs. This topic lists the HTTP error codes our APIs return, gives some examples of error messages to help you troubleshoot your calls, and offers recommendations on when to retry requests.
Tip: Request Rate and Payload Errors? For details of the errors returned when the API call request rate and payload limits are exceeded on our APIs, see the earlier topic in this section: Config API Limits and Ingest API Limits.
|HTTP Error Code||Reason Returned|
|403||Forbidden or Unauthorized|
|413||Response too large|
|429||Too Many Requests|
|500||Internal Error (might be mapped to something else)|
When you submit an invalid API call and one of these HTTP error codes is returned, an informative message is also returned, which is designed to help you correct the API call you initially made. The following sections provide some examples to illustrate.
NOTE: A Postman workspace was used for the error message examples.
PUT Update Meter call was made:
But the JSON request schema was not well-formed:
A 400 Bad Request is returned with a message in the return JSON body that identifies the JSON error:
PUT Update Meter call was made:
But an existing Data Field or Derived Field on the Meter has already been configured as the target usage data field for an Aggregation. Updating the Meter using the call to remove the existing Data Fields/Derived Fields and replace them with a single new Data Field would break that existing configuration:
A 400 Bad Request is returned with a message in the return JSON body that blocks the update to prevent the configuration disruption and explain why the request has been identified as a bad request:
GET List Meters call was made:
But the OrgId used in the path did not exist. A 403 Forbidden is returned with a message in the JSON body of the response:
A GET List OrgUsers call was made:
But the Bearer Token for the user making the call had expired. A 403 Forbidden is returned with a message that the call is Unauthorized in the JSON body of the response:
Tip: User Can't Authenticate? Note that although a Forbidden response is returned in this case, this does not mean the user is not allowed to retrieve a list of the Organization's Users - does not have the requisite permissions to do this - merely that the authentication credentials used have failed to give the user access. The user must obtain a fresh Bearer Token and retry the call whilst the new Token remains valid.
GET Retrieve Account call was made:
But the Account code was used in error instead of the id. A 404 Not Found is returned with a message in the return JSON body:
In general, HTTP error codes returned for failed calls indicate two types of error:
4XX codes. An error occurred on the client side.
5XX codes. An error occurred on the server side.
This means that for the HTTP error codes listed in the above section:
If a 500, 502, or 504 error is returned, we recommend you attempt a retry to see if the error has resolved.
If a 400, 403, or 404 error is returned, you should not attempt a retry of the call - you must look into the call you made and fix the call before attempting a retry.
If a 413 error is returned, the response to the call exceeds the payload limit imposed. You can review the call you've made and attempt to reduce the response payload - such as by applying filters in the request - and retry the call.
If a 429 error is returned (Too Many Requests), retries are valid. However, we recommend you wait at least 1 second before attempting a retry. If the second attempt fails, wait 3 seconds before attempting the call again, and so on, with an increased time gap before each successive retry. This method allows the request rate to fall back under the limit threshold and the 429 is no longer returned. For full details on request rate limits imposed on our APIs, see the earlier topic in this section: Config API Limits and Ingest API Limits
Login to the Support portal for additional help and to send questions to our Support team.