Errors - MX Documentation

The Platform API uses standard HTTP status codes to indicate whether a request succeeded. When a request fails, the response body includes an error object that describes what went wrong.

Error object

Error responses return an error object with the following fields:

Field	Description
`message`	A description of the error.
`status`	The HTTP status, in snake case (for example, `bad_request` or `not_found`).
`type`	The type of error, in snake case (for example, `record_not_unique` or `institution_maintenance_error`).

{
  "error": {
    "message": "An object with the given attributes already exists.",
    "status": "conflict",
    "type": "record_not_unique"
  }
}

Field-level errors

When request validation fails, some endpoints also return an errors object with a 422 Unprocessable Entity status. Each key is a request field, and each value is a list of messages for that field. More than one field can appear.

{
  "error": {
    "errors": {
      "user_guid": ["is required"]
    },
    "message": "The data provided cannot be processed.",
    "status": "unprocessable_entity",
    "type": "unprocessable_entity_error"
  }
}

Status codes

Status	Description
`200 OK`	The request succeeded, and the response includes content.
`202 Accepted`	The request succeeded, and MX is processing it. A job request also returns `202` when a job of the same type is already running for the member, or when a standard aggregation is requested before the minimum time between standard aggregations has passed.
`204 No Content`	The request succeeded, and the response has no content.
`400 Bad Request`	A required parameter is missing, or a premium aggregation job was requested for a member whose institution doesn’t support it. Also returned for institution blocking errors.
`401 Unauthorized`	The `Authorization` header is missing, or the `client_id` and `api_key` are invalid.
`403 Forbidden`	The request came from an IP address that isn’t on your allowlist, or the feature isn’t available to your client.
`404 Not Found`	The requested object, ID, or URL doesn’t exist. See 404 errors after creating an object.
`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. See Specify a version.
`409 Conflict`	An object with the given attributes already exists, or the member already has a job of a different type running.
`410 Gone`	The endpoint has been sunset and no longer accepts requests. See Deprecations.
`422 Unprocessable Entity`	The data provided can’t be processed. The response may include field-level errors.
`429 Too Many Requests`	You exceeded a rate limit. See Rate Limits.
`500`, `502`, `504`	An error occurred on MX’s servers.
`503 Service Unavailable`	The MX platform is being updated.

Institution blocking errors

Member operations and job requests may be blocked based on the institution’s status or client_status field. For these fields and their values, see the List Institutions and Read Institution endpoint pages. When a request is blocked, the API returns 400 Bad Request. The error.type starts with institution_, and error.message is written so you can show it to end users.

{
  "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"
  }
}

Scenario	`error.type`	`error.message`
Institution in maintenance	`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	`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`)	`institution_prevented_error`	The requested data isn’t available through this institution.
New connections blocked (`PREVENT_NEW`)	`institution_prevent_new_error`	This institution isn’t available for connection.
Verification blocked (`PREVENT_VERIFICATION`)	`institution_prevent_verification_error`	The requested data isn’t available through this connection.

When you receive a 400 for a member operation, check whether error.type starts with institution_. If it does, show error.message to the end user so they know why the operation failed.

404 errors after creating an object

A GET request sent immediately after creating an object may return 404 Not Found, even though the object was created. New objects usually become available right away, but it can occasionally take up to a second before they can be read. To avoid this error:

Use the create response instead of a follow-up GET. A successful create response includes the new object’s details.
If you need to send a GET right after creating an object, wait at least 500 milliseconds first.
If the 404 persists, confirm the object’s GUID and that you’re using the correct environment. If the issue continues, contact MX Support with the full request and response.

​Error object

​Field-level errors

​Status codes

​Institution blocking errors

​404 errors after creating an object

Error object

Field-level errors

Status codes

Institution blocking errors

404 errors after creating an object