Errors

The MX Platform API uses conventional HTTP response codes to indicate the success or failure of a request, with supplementary error messaging as needed within response bodies.

Status Codes

Status	Explanation
200 OK	Everything worked as expected with content returned.
202 Accepted	1. Everything worked and MX’s system is processing the request.
	2. When attempting a job on a member, a job of the same type is already running; e.g., calling aggregate member while a standard agg is still running, or calling verify member while a previous verification is still running.
	3. A standard aggregation has been attempted within the default minimum time between standard aggs.
204 No Content	Everything worked as expected without content returned.
400 Bad Request	1. A required parameter was missing.
	2. A premium aggregation-type job was requested, but the institution associated with the member does not support it.
401 Unauthorized	Invalid MX-API-Key or MX-Client-ID provided.
403 Forbidden	The request was made from a non-whitelisted address or the feature is not available to the client.
404 Not Found	Invalid item/id/URL requested.
405 Method Not Allowed	A constraint on the requested endpoint wasn’t met.
406 Not Acceptable	The request didn’t specify a valid API version.
409 Conflict	1. An object with the given attributes already exists.
	2. When attempting an aggregation on a member, the member already has an aggregation of a different type running; e.g., calling the verify endpoint while a standard aggregation is already running, or calling fetch statements while an identification aggregation is already running.
422 Unprocessable Entity	The data provided cannot be processed.
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.
500, 502, 504 Server errors	Something went wrong with MX’s servers.
503 Service Unavailable	The MX Platform is being updated.

Institution Blocking Errors

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

For complete details on institution blocking rules, see the Institution Overview.

Error Response Structure

_10

{

_10

"error": {

_10

"message": "This institution is temporarily unavailable due to scheduled system maintenance. Access will resume once maintenance is complete. Please try again later.",

_10

"status": "unprocessable_entity",

_10

"type": "institution_maintenance_error"

_10

}

_10

}

The error.message field contains text that can be displayed directly to end users. The specific message and error.type depend on the institution’s status.

Common Blocking Scenarios

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

Best Practices

• When you receive a 422 error for member operations, check the error.type to determine if it’s institution-related (types starting with institution_)
• Display error.message to users
• Provide clear feedback to users about why the operation failed due to institution unavailability or restrictions