+++
title = "API Error 422: Unprocessable Entity"
weight = 106
updated = 2026-10-13
aliases = ["/docs/api-error-422-unprocessable-entity.html", "/docs/troubleshooting/api-errors/422-unprocessable-entity/", "/docs/api/errors/422-unprocessable-entity/"]

[extra]
nav_title = "API Error 422: Unprocessable Entity"
weight = 50
+++

{{ legacy_api_notice() }}

An HTTP 422: Unprocessable Entity error occurs when the API could read a request, but can't do what it asks. This is a client-side error, meaning the problem is with the content of the request, and not the API. For example, the request asks to create a cluster on a plan that does not exist.

A request that the API can't read at all, because its body is not valid JSON, gets an [HTTP 400: Bad Request](@/docs/api/legacy/errors/400-bad-request/index.md) error instead. The API does not check the `Accept` header, so it never causes an error.

A request refused with a 422 changes nothing.

## Causes

[Creating a cluster](@/docs/api/legacy/endpoints/cluster-api/index.md#create-new-cluster) checks its parameters in this order, and stops at the first problem:

| Problem | Message |
| --- | --- |
| No `name` | `No name specified. Please provide a name for the cluster.` |
| No `plan` | `No plan specified. Please use the /plans endpoint for a list of available plans.` |
| A `plan` that is not available to your account | `Plan '[:plan]' not found. Please use the /plans endpoint for a list of available plans.` |
| A paid plan, on an account without a payment method | `Please add a payment method to your account.` |
| No `space` | `No space specified. Please use the /spaces endpoint for a list of available spaces.` |
| A `space` that is not available to your account | `Space not found.` |
| A `space` that is not shaped like a space path | `Invalid space path.` |
| A `release` that is not available to your account, or no release available for the plan | `Release not found.` |

[Updating a cluster](@/docs/api/legacy/endpoints/cluster-api/index.md#update-cluster) can be refused for:

| Problem | Message |
| --- | --- |
| The cluster has been destroyed | `Cluster [:slug] is terminated.` |
| A `plan` that is not available to your account | `Plan '[:plan]' not found. Please use the /plans endpoint for a list of available plans.` |
| An account without a payment method, unless the request moves the cluster to a free plan | `Please add a payment method to your account.` |
| A `name` the cluster can't take | The validation message, such as `Name is too long (maximum is 512 characters)` |
| A plan change that can't be made | A message saying why, such as `New price standard-fir must be different from the current price: standard-fir` |

When an update is refused, nothing in it is applied: a refused name leaves the plan alone, and a refused plan leaves the name alone.

[Destroying a cluster](@/docs/api/legacy/endpoints/cluster-api/index.md#destroy-cluster) can be refused for:

| Problem | Message |
| --- | --- |
| The cluster has already been destroyed | `Cluster [:slug] is terminated.` |
| A `name` that does not match the cluster's name exactly | ``The `name` you passed does not match the name of cluster [:slug].`` |

## Example

A call to the API that results in an HTTP 422: Unprocessable Entity error looks like this:

```json
{
  "errors": [
    "Plan 'sandboxing' not found. Please use the /plans endpoint for a list of available plans."
  ],
  "status": 422
}
```

The `"status": 422` key indicates the HTTP 422: Unprocessable Entity error.

## Troubleshooting

The first step in troubleshooting this error is to read the message in the response, which names the problem. Then check the value it points to against the [Plans](@/docs/api/legacy/endpoints/plans-api/index.md), [Spaces](@/docs/api/legacy/endpoints/spaces-api/index.md) and [Releases](@/docs/api/legacy/endpoints/releases-api/index.md) APIs: plans and releases are passed by slug, and spaces by their full path, such as `omc/bonsai/us-east-1/common`.

If all else fails, you can always [contact support](mailto:support@bonsai.io) and we will be glad to assist.