> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m3ter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

* [HTTP Error Codes](#http-error-codes)
* [400 - Bad Request Examples](#400-bad-request-examples)
* [403 - Forbidden Example](#403-forbidden-example)
* [403 - Unauthorized Example](#403-unauthorized-example)
* [404 - Not Found Example](#404-not-found-example)
* [Retry Recommendations](#retry-recommendations)

<Tip>
  **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](/guides/m3ter-apis/config-api-limits) and [Ingest API Limits](/guides/m3ter-apis/ingest-api-limits).
</Tip>

## 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.

<Tip>
  **NOTE:** A Postman workspace was used for the error message examples.
</Tip>

## 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:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049109-400badrequest4.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=86dd64aff1ed89408da92588a5d89ee0" style={{ maxWidth: 'min(700px, 100%)' }} width="1106" height="544" data-path="images/1665049109-400badrequest4.png" />

A **400 Bad Request** is returned with a message in the return JSON body that identifies the JSON error:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049278-400badrequest5.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=1af219ec32b1bb23f105b8b62b33d231" style={{ maxWidth: 'min(700px, 100%)' }} width="1096" height="238" data-path="images/1665049278-400badrequest5.png" />

### 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:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049518-400badrequest2.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=aa8738b29bbd3c0de3415e46260decc5" style={{ maxWidth: 'min(700px, 100%)' }} width="1110" height="489" data-path="images/1665049518-400badrequest2.png" />

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:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049563-400badrequest3.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=10cd06e7be978e477eee448875ddfbfa" style={{ maxWidth: 'min(700px, 100%)' }} width="1109" height="228" data-path="images/1665049563-400badrequest3.png" />

## 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:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049804-404forbidden1.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=7d0bfe3c6fed03cce66848f62ac22623" style={{ maxWidth: 'min(700px, 100%)' }} width="1111" height="410" data-path="images/1665049804-404forbidden1.png" />

## 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](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:

<img src="https://mintcdn.com/m3ter/sSeshoNuulAewaeU/images/1695724542-403unauthorized1.png?fit=max&auto=format&n=sSeshoNuulAewaeU&q=85&s=2ac125105ca41f2bffd41657adad690f" style={{ maxWidth: 'min(700px, 100%)' }} width="1056" height="400" data-path="images/1695724542-403unauthorized1.png" />

<Tip>
  **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.
</Tip>

## 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:

<img src="https://mintcdn.com/m3ter/Vo1TZsYmBMDUxOdH/images/1665049994-404-not-found1.png?fit=max&auto=format&n=Vo1TZsYmBMDUxOdH&q=85&s=6a46cbc79e117e93c0c0467e91c7f4f3" style={{ maxWidth: 'min(700px, 100%)' }} width="1110" height="422" data-path="images/1665049994-404-not-found1.png" />

## 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](/guides/m3ter-apis/http-error-codes#http-error-codes):

* 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](/guides/m3ter-apis/config-api-limits) and [Ingest API Limits](/guides/m3ter-apis/ingest-api-limits)