Error handling
Learn the best practice for handling errors from the Maesn API
Error handling
Handling error messages based on the response codes is critical to implement robust integrations. In this guide we provide an overview of the HTTP response codes you can expect from the Maesn API and how to handle them in an effective way.
Response code categories
The Maesn API uses standard HTTP response codes, but only some codes are in active use:
- 2xx: Successful responses
- 4xx: Client errors
- 5xx: Server errors
Implementing error handling logic
Below are the types of errors returned by Maesn and some guidance for how to handle the respective response codes:
4xx: Client errors
| Code | Issue | Description | Retry | Tips & Tricks |
|---|---|---|---|---|
| 400 | Bad request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed syntax, invalid request, etc.) | No | Check our docs to see if the endpoint you want to use is supported for the system and check if the target system has the data you want to read or write. Ensure that the correct client credentials for the target system are configured in the Maesn API. |
| 401 | Unauthorized | The request has not been applied because it lacks valid authentication credentials for the target resource | No | During development make sure that you have a valid ACCOUNT-KEY token and that it has not expired or been invalidated. In proudction, the end user will need to re-authetnicate. |
| 403 | Forbidden | The server understood the request but refuses to authorize it | No | Check that you are sending a valid X-API-KEY and, if required, a valid X-ACCOUNT-KEY with your request. |
| 404 | Not Found | The Maesn API did not find the requested target resource | No | Check that the syntax of the URL is correct and that the subdomain entered is valid. If all is correct, contact Maesn support. |
| 405 | Method Not Allowed | The method received in the request-line is known by the origin server but not supported by the target system | No | Check our docs to see if the endpoint you want to use is due to be implemented in the future or cannot be supported by that system at all. |
| 429 | Too Many Requests | The user has sent too many requests in a given amount of time (“rate limiting”) | Yes | Retry using the logic explained in the Retry-section below. |
5xx: Server errors
| Code | Issue | Description | Retry | Tips & Tricks |
|---|---|---|---|---|
| 500 | Internal server error | The Maesn API encountered an unexpected condition that prevented it from fulfilling the request. | Yes | Retry using the logic explained in the Retry-section below. If the error persists, contact Maesn support. |
Implementing automatic retries
It is considered good practice to implement retry logic when encountering specific error codes. See our recommended logic for the respective response code you get back from the Maesn API below:
| Code | Issue | Description | Retry logic |
|---|---|---|---|
| 429 | Too Many Requests | The user has sent too many requests in a given amount of time (“rate limiting”) | Retry the request after an initial one-minute delay and increase the delay exponentially with each additional retry. |
| 500 | Internal server error | The Maesn API encountered an unexpected condition that prevented it from fulfilling the request. | Retry the request after an initial 15-30 second delay and increase the delay exponentially with each additional retry. |
“Exponential backoff” means the first retry is made after a given delay, e.g, one minute, the next after two minutes, then 4 minutes, then 8 minutes until a defined threshold where retrying stops and the request is considered failed.