HTTP Error Codes

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 Codes

HTTP Error Code	Reason Returned
400	Bad Request
403	Forbidden or Unauthorized
404	Not Found
413	Response too large
429	Too Many Requests
500	Internal Error (might be mapped to something else)
502	Bad Gateway
504	Gateway Timeout

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.

400 - Bad Request Examples

Example 1 - Update Meter > Invalid JSON Request Body Used

A PUT Update Meter call was made:

https://api.m3ter.com/organizations/ZZ6d788d-5174-4e8b-9d69-a41f4671fcYY/meters/06f6b50c-a868-4ca6-b287-448e507d5248

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:

Example 2 - Update Meter > Request Breaks Configuration

A PUT Update Meter call was made:

https://api.m3ter.com/organizations/ZZ6d788d-5174-4e8b-9d69-a41f4671fcYY/meters/06f6b50c-a868-4ca6-b287-448e507d5248

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:

403 - Forbidden Example

Example - List Meters > Unknown Org Id Used

A GET List Meters call was made:

https://api.m3ter.com/organizations/ZZ6d788d-5174-4e8b-9d69-a41f4671fcYY/meters

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:

403 - Unauthorized Example

Example - List OrgUsers > expired Bearer Token used

A GET List OrgUsers call was made:

https://api.m3ter.com/organizations/396d788d-XXRRS-4e8b-9d69-a41f4671fc33/users

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.

404 - Not Found Example

Example - Retrieve Account > Account Not Found

A GET Retrieve Account call was made:

https://api.m3ter.com/organizations/396d788d-XXRRS-4e8b-YUYU-a41f4671fc33/accounts/game_dev_indie

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:

Retry Recommendations

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