HTTP Status Codes and Errors

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.
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 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, please see feature documentation for more information.
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.