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

CodeIssueDescriptionRetryTips & Tricks
400Bad requestThe 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.)NoCheck 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.
401UnauthorizedThe request has not been applied because it lacks valid authentication credentials for the target resourceNoDuring 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.
403ForbiddenThe server understood the request but refuses to authorize itNoCheck that you are sending a valid X-API-KEY and, if required, a valid X-ACCOUNT-KEY with your request.
404Not FoundThe Maesn API did not find the requested target resourceNoCheck that the syntax of the URL is correct and that the subdomain entered is valid. If all is correct, contact Maesn support.
405Method Not AllowedThe method received in the request-line is known by the origin server but not supported by the target systemNoCheck 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.
429Too Many RequestsThe user has sent too many requests in a given amount of time (“rate limiting”)YesRetry using the logic explained in the Retry-section below.

5xx: Server errors

CodeIssueDescriptionRetryTips & Tricks
500Internal server errorThe Maesn API encountered an unexpected condition that prevented it from fulfilling the request.YesRetry 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:

CodeIssueDescriptionRetry logic
429Too Many RequestsThe 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.
500Internal server errorThe 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.