Errors - MX Documentation

The Platform API reports these kinds of errors:

Request errors: The request couldn’t be processed. The API returns a 4xx or 5xx status and an error object. See Status codes.
Institution blocking errors: A Create Member, Update Member, or account verification request is rejected before it starts because of the institution’s status. The API returns 422 Unprocessable Entity with an error object. See the Institution Blocking Errors section of the Members Overview page.
Member connection errors: The request succeeds, but aggregating the member fails at the institution, for example because of invalid credentials or an institution outage that MX discovers during aggregation. The API returns a successful response and describes the problem in the member’s error field. See the Member Connection Errors section of the Members Overview page.

Error object

When a request fails, the response includes an error object with the following fields. This object is different from the member’s error field, which describes member connection errors.

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 `unprocessable_entity_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.
`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. Also returned when a member request is blocked because of the institution’s status. See the Institution Blocking Errors section of the Members Overview page.
`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.

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

​404 errors after creating an object

Error object

Field-level errors

Status codes

404 errors after creating an object