Errors - MX Documentation

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 rate limit. See details below.
`500, 502, 504 Server errors`	Something went wrong with MX’s servers.
`503 Service Unavailable`	The MX Platform is being updated.

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 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 more details, see Institution Overview.

Error Response Structure

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

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	400	`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	400	`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)	400	`institution_prevented_error`	The requested data isn’t available through this institution.
New connections blocked (PREVENT_NEW)	400	`institution_prevent_new_error`	This institution is not available for connection.
Verification blocked (PREVENT_VERIFICATION)	400	`institution_prevent_verification_error`	The requested data isn’t available through this connection.

Best Practices

When you receive a 400 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

​Status Codes

​429 Too Many Requests

​Institution Blocking Errors

​Error Response Structure

​Common Blocking Scenarios

​Best Practices