+++
title = "API Errors"
weight = 91
updated = 2026-11-03
aliases = [
  "/docs/api/errors/unauthorized/",
  "/docs/api/errors/missing_scope/",
  "/docs/api/errors/feature_not_enabled/",
  "/docs/api/errors/rate_limited/",
  "/docs/api/errors/too_many_failed_authentications/",
  "/docs/api/errors/invalid_json/",
  "/docs/api/errors/body_required/",
  "/docs/api/errors/invalid_parameter/",
  "/docs/api/errors/name_confirmation_required/",
  "/docs/api/errors/name_mismatch/",
  "/docs/api/errors/not_found/",
  "/docs/api/errors/validation_failed/",
  "/docs/api/errors/payment_method_required/",
  "/docs/api/errors/payment_failed/",
  "/docs/api/errors/cluster_terminated/",
  "/docs/api/errors/plan_change_refused/",
  "/docs/api/errors/action_in_progress/",
  "/docs/api/errors/idempotency_key_reused/",
  "/docs/api/errors/idempotency_key_in_use/",
  "/docs/api/errors/idempotency_replay_unavailable/",
  "/docs/api/errors/metrics_unavailable/",
  "/docs/api/errors/internal_error/",
]

[extra]
nav_title = "Errors"
weight = 40
+++

Every error from the Bonsai API v1 is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem, with the content type `application/problem+json`:

```json
{
  "type": "https://bonsai.io/docs/api/errors/invalid_parameter",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_parameter",
  "detail": "The body doesn't match its schema. See details.",
  "details": [
    { "field": "/plan", "message": "plan is required." }
  ]
}
```

| Field | What it is |
|---|---|
| `code` | What went wrong, as a stable snake_case string. **Branch on this.** |
| `status` | The HTTP status, repeated. |
| `type` | A link to this code's section of this page. |
| `title` | The HTTP status's name, like `Bad Request`. |
| `detail` | What went wrong, for people. It can change, so don't parse it. |
| `details` | The fields at fault, if any. Each has a `field` (a JSON pointer into the body, like `/plan`, or a query parameter's name, like `limit`), and a `message`. On `missing_scope`, it also has the `scope`. |
| `action_url` | Only when a person has to fix something, such as adding a card: the page where they can. |

More codes may be added. Handle a code you don't know by its HTTP status. Each operation's [reference](@/docs/api/reference/_index.md) lists the codes it can answer.

The [legacy API](@/docs/api/legacy/errors/_index.md) has its own error format, without codes.

## 400 Bad Request

The request is malformed. Fix it before sending it again.

### invalid_json {#invalid_json}

The body isn't valid JSON.

### body_required {#body_required}

The operation needs a JSON object body, and got none, or an empty object.

### invalid_parameter {#invalid_parameter}

A query parameter is out of range, or the body doesn't match the operation's schema: a field is missing, has the wrong type, or isn't one the operation takes. `details` names each field at fault.

### name_confirmation_required {#name_confirmation_required}

Deleting a cluster needs its current name as `?name=`, to confirm, and the request had none.

## 401 Unauthorized

### unauthorized {#unauthorized}

The request has no valid token. Either the `Authorization` header is missing or doesn't use `Bearer`, or the token is unknown, revoked or expired. v1 takes Bearer authentication only: `Authorization: Bearer bonsai_<key>_<secret>`. See [Authentication](@/docs/api/authentication/index.md).

## 403 Forbidden

### missing_scope {#missing_scope}

The token doesn't have the scope this operation needs. `details[].scope` names it. Create a token with that scope; see [scopes](@/docs/api/authentication/index.md#scopes).

### feature_not_enabled {#feature_not_enabled}

The operation needs a feature the account doesn't have: top queries for a cluster without query logs, or an `rwm` or `acl` credential where those aren't enabled. Contact [support@bonsai.io](mailto:support@bonsai.io) to have it turned on.

## 404 Not Found

### not_found {#not_found}

There's no such cluster, Action, credential, plan or path in the token's account. A cluster in another account is a 404 too, not a 403. A revoked credential is a 404, since it's gone from the API.

## 409 Conflict

The request clashes with something in progress. These are safe to retry later.

### action_in_progress {#action_in_progress}

An Action of the same kind is already running on the cluster. Wait for it to finish, then try again. See [Actions](@/docs/api/actions/index.md#one-change-at-a-time).

### idempotency_key_in_use {#idempotency_key_in_use}

A request with the same `Idempotency-Key` is still being handled. Retry after the seconds in `Retry-After`. See [retrying safely](@/docs/api/retrying-safely/index.md).

### idempotency_replay_unavailable {#idempotency_replay_unavailable}

A request with this `Idempotency-Key` succeeded, but what it made can't be returned again, such as a credential that has since been revoked. Use a new key if you mean to make a new one.

## 422 Unprocessable Content

The request is well-formed, but Bonsai declined it.

### validation_failed {#validation_failed}

A value isn't acceptable: an unknown or unavailable plan, region, space or release, a name that's too long, a credential the cluster can't take, or revoking a cluster's last `rw` credential. `details` names the fields at fault, where there are any. Enterprise plans that need their own servers can't be created through the API; contact [support@bonsai.io](mailto:support@bonsai.io) for those.

### name_mismatch {#name_mismatch}

The `name` sent to confirm a delete isn't the cluster's current name. Names are matched exactly.

### payment_method_required {#payment_method_required}

A paid plan needs a payment method on the account, unless the account is billed by invoice, and there's none. `action_url` is a secure Stripe page where anyone with the link can add a card, without logging in to Bonsai. The card becomes the account's default. The link lasts at least an hour; send the request again for a fresh one.

Nothing was started, so once the card is added, send the same request again, with the same `Idempotency-Key` if it had one.

### payment_failed {#payment_failed}

Creating a cluster charges the account before building anything, and the charge was refused: there's no card, or it was declined. Nothing was built. `action_url` is a page where a card can be added, as for `payment_method_required`. Once it's added, send the same request again.

An Action started through the legacy API can also fail with `payment_failed`, as its `error.code`. See [Actions](@/docs/api/actions/index.md#failures).

### cluster_terminated {#cluster_terminated}

The cluster has been deleted, so it can't be changed. A delete retried without an `Idempotency-Key` gets this too.

### plan_change_refused {#plan_change_refused}

The cluster can't move to that plan. Some plans can only move to plans of certain tiers.

### idempotency_key_reused {#idempotency_key_reused}

This `Idempotency-Key` was already sent with a different request. Use a new key for each change.

## 429 Too Many Requests

Both carry a `Retry-After` header with the seconds to wait.

### rate_limited {#rate_limited}

The token, or for operations without a token, the IP address, went over its [rate limit](@/docs/api/rate-limits/index.md).

### too_many_failed_authentications {#too_many_failed_authentications}

Too many requests from this IP address failed to authenticate. Check the token you're sending.

## 500 Internal Server Error

### internal_error {#internal_error}

Something went wrong on Bonsai's side. It's been reported to us. If it keeps happening, write to [support@bonsai.io](mailto:support@bonsai.io).

## 503 Service Unavailable

### metrics_unavailable {#metrics_unavailable}

The store behind a cluster's usage, metrics or top queries didn't answer. Retry after the seconds in `Retry-After`. The API answers this rather than an empty list, so an empty list always means there's no data.
