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. |
Error Types
Not authorized
We were unable to authorize the request. This can happen for several reasons, including a missing or incorrect X-API-KEY or X-ACCOUNT-KEY, revoked user access via the target system, or expired access and refresh tokens. Some systems impose a maximum lifespan on refresh tokens (for example, 30 days), so re-authentication must be accounted for.
Your application should handle 401 errors and allow the user to reconnect or reauthorize the integration promptly.
Invalid parameters
The request is missing one or more required parameters in the path or body, or the provided parameter values are invalid. Any missing or invalid parameters will be detailed in the errors array of the response.
Target system credentials error
The request to the target system could not be authorized. Ensure that the client credentials for the target system you are trying to access have been configured correctly and are authorized for use.
Target system not found
The requested target system could not be found. Verify that your target system string is correct.
Target system error
A Unified API request to a downstream target system returned an unexpected error. The original error response and HTTP status code are included in the downstreamErrors array of the response.
Target system rate limit error
Too many requests were sent to the target system in a short period. Each system has its own rate limits, you will need to retry after some delay.
Resource not supported
The endpoint being called is not implemented for the specified target system. This means that the functionality is not currently available for that integration.
Inactive user
The end-user account is currently inactive. To proceed, the user must re-authenticate their session with the target system.
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.
Target system errors
downstreamErrors
When the underlying target system returns an error, the Maesn unified API will include the data returned by the target system related to the error in the response data (in the downstreamErrors array). For example, 500 error is returned, because the reference to the GL account was invalid.
