Errors - MX Documentation

Status Codes

Status	Explanation
200 OK	Everything worked as expected with content returned.
202 Accepted	• Everything worked and MX’s system is processing the request. • When attempting a job on a member, a job of the same type is already running. • A standard aggregation has been attempted within the default minimum time between standard aggregations.
204 No Content	Everything worked as expected without content returned.
400 Bad Request	• A required parameter was missing. • A premium aggregation-type job was requested, but the institution associated with the member doesn’t support it.
401 Unauthorized	An invalid `MX-API-Key` or `MX-Client-ID` was provided.
403 Forbidden	The request was made from a non-whitelisted address or the feature isn’t available to the client.
404 Not Found	An invalid item, ID, or URL was 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	• An object with the given attributes already exists. • When attempting an aggregation on a member, the member already has an aggregation of a different type running.
422 Unprocessable Entity	The data provided can’t be processed.
429 Too Many Requests	The maximum number of concurrent connections or rate limits has been exceeded. See details below.
500, 502, 504 Server error	Something went wrong with MX’s servers.
503 Service Unavailable	The MX Platform is being updated.

404 Errors

When creating a new object, an immediate subsequent GET request may result in a 404 Not Found error, even following a successful POST operation. This behavior is due to data propagation. While this process is typically instantaneous, a brief delay (under one second) can occasionally occur before the object is fully available for read operations across all environments. This is expected behavior, and the following best practices can help avoid this error:

Use the POST response for validation. A 200 status code confirms successful creation, and the response body includes all details of the newly created object.
If your workflow requires a GET request immediately after POST operation, add a delay of at least 500 milliseconds.
If a 404 persists after waiting, verify the object GUID, ensure you’re using the correct environment, and review your API logs. If the issue persists, contact MX Support and provide full request and response details.

429 Too Many Requests

The 429 Too Many Requests error is triggered when you exceed the maximum number of concurrent connections or requests per second (RPS). Requests receiving a 429 status code should be retried after the rate limit resets. To prevent this error, decrease the number of concurrent connections or requests per second. Rate limiting is applied per client with the following thresholds:

GET: 2,000 RPS
POST: 750 RPS
PUT: 750 RPS
DELETE: 150 RPS

Individual features may implement specific rate limit overrides.

Institution Blocking Errors

Member operations (GET, POST) 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 isn’t 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

​404 Errors

​429 Too Many Requests

​Institution Blocking Errors

​Error Response Structure

​Common Blocking Scenarios

​Best Practices