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 | Invalid parameters | Client-side validation failed. See validationErrors for details. | No | Validate payload against the schema. Inspect each item in validationErrors and fix before retrying. |
| 401 | Unauthorized | Missing or invalid authentication credentials. | No | In development ensure a valid X-ACCOUNT-KEY that hasn’t expired or been revoked. In production the end user must re-authenticate. |
| 403 | Forbidden / Inactive user | Access denied or the end-user account is inactive. | No | Verify X-API-KEY and, if required, X-ACCOUNT-KEY. Confirm the user account is active. |
| 404 | Not Found / Not Supported | Resource not found in the target system, or the endpoint isn’t available for that target system. | No | Check URL syntax and subdomain. Confirm the endpoint is supported by the chosen target system. Review downstream errors from the target system. |
| 405 | Target system not found | The specified target system identifier is unknown. | No | Verify the target system code/tenant mapping exists for this account. |
| 429 | Too Many Requests | You are being rate-limited. | Yes | Implement exponential backoff with jitter. Honor any Retry-After header. Refer to the retry guidance 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
Handle errors according to their type to build more stable and predictable integrations.Not authorized
We were unable to authorize the request. This can happen for several reasons, including a missing or incorrectX-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 theerrors 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 thedownstreamErrors 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. |
Error structure
All API errors are returned inside the top-level errors object. Fieldscontext: includes{ targetSystem, unifiedApi, timestamp }downstreamErrors[]: errors reported directly by the connected target systemvalidationErrors[]: input issues detected by Maesn before the request is sentmessage: short explanation of what went wrong.type: standardized error category (invalid_parameters, not_authorized, inactive_user, resource_not_supported, target_system_not_found, target_system_error, target_system_rate_limit_error, TARGET_SYSTEM_CREDENTIALS_ERROR).statusCode: standard HTTP status code.
Downstream errors
When the target system rejects or fails a request, Maesn passes its original error message through in downstreamErrors. This lets you see exactly what the external system reported (for example, an invalid account code). These errors appear only when the error type istarget_system_error.
Review the details from the provider, correct the issue, and retry your request.
Validation errors
Validation errors occur when your request doesn’t meet Maesn’s input requirements. Before sending the request to the target system, Maesn checks field formats, required values, and data types. Any problems are listed in validationErrors, showing the field path and a short message. Fix the highlighted fields and resend the request. These errors appear only when the error type isinvalid_parameters.