Skip to main content
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 CodeHTTP Status CodeStatusError Description
4001400Bad RequestRequired params missing.
4002400Bad RequestOne or more parameters were not permitted.
4003400Bad RequestCannot create/update goal. Monthly Contribution from the MonthlyCashFlowProfile must be greater than 0.
null400Bad RequestThe date range provided was invalid.
null400Bad RequestMonthly Cash Flow Profile is invalid.
null400Bad RequestA submitted parameter field is invalid.
null400Bad RequestYou cannot aggregate a manual member.
null400Bad RequestAccount guid is not valid.
4011401UnauthorizedThe session token used in this request has expired.
null401UnauthorizedInvalid API token.
null403ForbiddenOperation is forbidden.
null404Not FoundWe were unable to find the record you requested.
null405Method Not AllowedMethod not allowed.
null406Not AcceptableThe request cannot be accepted. A required header may be missing or invalid.
4220422Unprocessable EntityRecord could not be saved. See note below.
4221422Unprocessable EntityWhen attempting to auto-generate budgets, no category contained the minimum required number of transactions. See the auto-generate budget endpoint for additional information.
4230422Unprocessable EntityInstitution is unavailable or blocked. See Institution Blocking Errors.
null422Unprocessable EntityRecord could not be saved. One or more parameters is invalid.
null429Too Many RequestsThis error is triggered when exceeding the maximum number of concurrent connections or rate limit. See details below.
null500Internal Server ErrorAn unknown error has occurred.
null404Not FoundChallenge question expired. Please try again.
null400Bad RequestThe 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

ScenarioHTTP Statuserror.codeerror.message
Institution in maintenance4224230This institution is temporarily unavailable due to scheduled system maintenance. Access will resume once maintenance is complete. Please try again later.
Institution unavailable4224230This institution is experiencing technical issues that are preventing successful connections. It’s unclear when this will be resolved.
Data not available4224230The requested data isn’t available through this institution.
New connections blocked4224230This institution is not available for connection.
Verification blocked4224230The 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