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 / Target system not found	Resource not found in the target system, or the specified target system identifier is unknown.	No	Check URL syntax and subdomain. Verify the target system code/tenant mapping exists for this account.
405	Not Supported	The endpoint isn’t available for that target system.	No	Confirm the endpoint is supported by the chosen target system. Review downstream errors from the target system.
409	Conflict	The request could not be completed due to a conflict with the current state of the resource.	No	The most common cause of this error is trying to create a resource that already exists. Check the data you are sending in the request body.
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.
503	Service Unavailable	The target API endpoint is temporarily unavailable, likely due to maintenance or overload.	Yes	Retry using the logic explained in the Retry section below. If the error persists, contact Maesn support.

Error structure

All API errors are returned inside the top-level errors object. The error response will look as follows

{
  "errors": {
      "context": {
          "targetSystem": "snelstart",
          "unifiedApi": "Accounting",
          "timestamp": "2026-02-10T14:59:59.426Z"
      },
      "downstreamErrors": [],
      "message": "Invalid parameters, please check the validationErrors array for details.",
      "statusCode": 400,
      "type": "invalid_parameters",
      "validationErrors": [
          "Contact type is invalid or missing. Contact type must be COMPANY."
      ]
  }
}

Fields

context: includes { targetSystem, unifiedApi, timestamp }
downstreamErrors[]: errors reported directly by the connected target system
message: short explanation of what went wrong.
statusCode: standard HTTP status code.
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, conflict, service_unavailable).
validationErrors[]: input issues detected by Maesn before the request is sent

Error Types

Handle errors according to their type to build more stable and predictable integrations.

Not authorized (`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 (`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 validationErrors array of the response.

Target system credentials error (`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 (`target_system_not_found`)

The requested target system could not be found. Verify that your target system string is correct.

Target system error (`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 (`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 (`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 (`inactive_user`)

The end-user account is currently inactive. To proceed, the user must re-authenticate their session with the target system.

Conflict (`conflict`)

The request could not be completed due to a conflict with the current state of the resource. The most common cause of this error is trying to create a resource that already exists.

Service Unavailable (`service_unavailable`)

The API endpoint is temporarily unavailable, likely due to maintenance or overload. Retry using the logic explained in the Retry section below. If the error persists, reach out to us.

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.
503	Service Unavailable	The target API endpoint is temporarily unavailable, likely due to maintenance or overload.	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.

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 is target_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 is invalid_parameters.

Get started

Guides

Integrations

Use cases

API reference

Knowledgebase

Error handling

Error handling

Response code categories

Implementing error handling logic

4xx: Client errors

5xx: Server errors

Error structure

Error Types

Not authorized (`not_authorized`)

Invalid parameters (`invalid_parameters`)

Target system credentials error (`target_system_credentials_error`)

Target system not found (`target_system_not_found`)

Target system error (`target_system_error`)

Target system rate limit error (`target_system_rate_limit_error`)

Resource not supported (`resource_not_supported`)

Inactive user (`inactive_user`)

Conflict (`conflict`)

Service Unavailable (`service_unavailable`)

Implementing automatic retries

Downstream errors

Validation errors

​Error handling

​Response code categories

​Implementing error handling logic

​4xx: Client errors

​5xx: Server errors

​Error structure

​Error Types

​Not authorized (not_authorized)

​Invalid parameters (invalid_parameters)

​Target system credentials error (target_system_credentials_error)

​Target system not found (target_system_not_found)

​Target system error (target_system_error)

​Target system rate limit error (target_system_rate_limit_error)

​Resource not supported (resource_not_supported)

​Inactive user (inactive_user)

​Conflict (conflict)

​Service Unavailable (service_unavailable)

​Implementing automatic retries

​Downstream errors

​Validation errors

Error handling

Response code categories

Implementing error handling logic

4xx: Client errors

5xx: Server errors

Error structure

Error Types

Not authorized (`not_authorized`)

Invalid parameters (`invalid_parameters`)

Target system credentials error (`target_system_credentials_error`)

Target system not found (`target_system_not_found`)

Target system error (`target_system_error`)

Target system rate limit error (`target_system_rate_limit_error`)

Resource not supported (`resource_not_supported`)

Inactive user (`inactive_user`)

Conflict (`conflict`)

Service Unavailable (`service_unavailable`)

Implementing automatic retries

Downstream errors

Validation errors