> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Platform API error responses: the error object, HTTP status codes, institution blocking errors, and 404 errors after creating an object.

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`). |

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](./aggregation#standard-aggregation-throttling) 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](#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](#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](./versioning#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](./deprecations). |
| `422 Unprocessable Entity` | The data provided can't be processed. The response may include [field-level errors](#field-level-errors). |
| `429 Too Many Requests` | You exceeded a rate limit. See [Rate Limits](./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.

```json theme={null}
{
  "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](https://support.mx.com/) with the full request and response.