HTTP Status Codes and Errors - MX Documentation

Error codes and messages are for logging and for informational purposes only and may change from time to time. Do not check for specific codes or messages as this may break your integration. The HTTP status response codes are sufficient for an integration workflow and processing of the error response body is not needed. The Nexus API uses conventional HTTP status codes to indicate success or failure of an API request. In general, codes in the 2XX range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with the MX Platform. On success, an HTTP 200 SUCCESS will be returned. Most successful DELETE requests will return with a status code of 200 and an empty response body, e.g. {}. However, certain endpoints — such as delete scheduled payment — return with a status of 204: No Content without an empty response body. Please pay close attention to the documentation for individual delete endpoints. On failure, a non-2XX HTTP status code will be returned, along with an error response body. Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. To compensate for this, endpoints may respond with a body containing more information about the error. An error response body consists of a code and a message.

A 422 error with a 4220 code can occur on a create member request for the following reasons:
The user already has a member connecting it to the same institution, using the same login credential. The duplicate member is not allowed.
The provided external_guid value already exists in a member belonging to a user in the same client. Please use a unique value.
The provided institution_guid does not exist.

Error Code	HTTP Status Code	Status	Error Description
`4001`	400	Bad Request	Required params missing.
`4002`	400	Bad Request	One or more parameters were not permitted.
`4003`	400	Bad Request	Cannot create/update goal. Monthly Contribution from the MonthlyCashFlowProfile must be greater than 0.
null	400	Bad Request	The date range provided was invalid.
null	400	Bad Request	Monthly Cash Flow Profile is invalid.
null	400	Bad Request	A submitted parameter field is invalid.
null	400	Bad Request	You cannot aggregate a manual member.
null	400	Bad Request	Account guid is not valid.
`4011`	401	Unauthorized	The session token used in this request has expired.
null	401	Unauthorized	Invalid API token.
null	403	Forbidden	Operation is forbidden.
null	404	Not Found	We were unable to find the record you requested.
null	405	Method Not Allowed	Method not allowed.
null	406	Not Acceptable	The request cannot be accepted. A required header may be missing or invalid.
`4220`	422	Unprocessable Entity	Record could not be saved. See note below.
`4221`	422	Unprocessable Entity	When attempting to auto-generate budgets, no category contained the minimum required number of transactions. See the auto-generate budget endpoint for additional information.
`4230`	422	Unprocessable Entity	Institution is unavailable or blocked. See Institution Blocking Errors.
null	422	Unprocessable Entity	Record could not be saved. One or more parameters is invalid.
null	429	Too Many Requests	This error is triggered when exceeding the maximum number of concurrent connections or rate limit. See details below.
null	500	Internal Server Error	An unknown error has occurred.
null	404	Not Found	Challenge question expired. Please try again.
null	400	Bad Request	The credential GUIDs submitted are no longer valid. Check the institution required credentials endpoint for the most recent credentials.

429 Too Many Requests

This error is triggered when exceeding the maximum number of concurrent connections, or the rate limit for requests per second (rps) is surpassed. Requests receiving a 429 status code should be retried once the rate limit window has expired. To prevent this error, decrease the number of concurrent connections or the number of requests per second. Rate limiting is applied per client with the following thresholds:

GETs: 2000/rps
POSTs: 750/rps
PUTs: 750/rps
DELETEs: 150/rps

Individual features may implement specific rate limit overrides.

Institution Blocking Errors

Member operations (create, update) and job creation (verify, identify) may be blocked based on an institution’s status or client_status fields. When blocked, the API returns a 422 Unprocessable Entity error with a user-friendly message.

Error Response Structure

{
  "error": {
    "code": 4230,
    "message": "This institution is temporarily unavailable due to scheduled system maintenance. Access will resume once maintenance is complete. Please try again later.",
    "status": "unprocessable_entity"
  }
}

The error.message field contains text that can be displayed directly to end users. The specific message depends on the institution’s status or client_status.

Common Blocking Scenarios

Scenario	HTTP Status	error.code	error.message
Institution in maintenance	422	4230	This institution is temporarily unavailable due to scheduled system maintenance. Access will resume once maintenance is complete. Please try again later.
Institution unavailable	422	4230	This institution is experiencing technical issues that are preventing successful connections. It’s unclear when this will be resolved.
Data not available	422	4230	The requested data isn’t available through this institution.
New connections blocked	422	4230	This institution is not available for connection.
Verification blocked	422	4230	The requested data isn’t available through this connection.

Best Practices

When you receive a 422 error with code 4230 for member operations, the error is institution-related
Display error.message to users as it provides clear, user-friendly explanations
Provide clear feedback to users about why the operation failed due to institution unavailability or restrictions

​429 Too Many Requests

​Institution Blocking Errors

​Error Response Structure

​Common Blocking Scenarios

​Best Practices

429 Too Many Requests

Institution Blocking Errors

Error Response Structure

Common Blocking Scenarios

Best Practices