# API errors

URL: https://docs.clatri.com/en/api/errors/

> The Clatri API error codes: what each one means, its HTTP status and what to do to fix it from your integration.

When a call to the [Clatri API](https://docs.clatri.com/en/api/) fails, the response is `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)):

```json
{
  "type": "https://docs.clatri.com/api/errors#tool_error",
  "title": "The tool could not complete the request",
  "status": 422,
  "detail": "Error: account not found.",
  "code": "tool_error",
  "request_id": "req_6c1d0e2a9b7f4e3c8a5d1f0b2e4c6a8d"
}
```

- **`code`** is stable: use it in your code to decide what to do. New codes can appear, but existing ones don't change within `v1`.
- **`type`** links to the section of this page that explains that code.
- **`title`** and **`detail`** are for humans to read, not to compare against.
- **`request_id`** identifies the call (also in the `Clatri-Request-Id` header). Include it if you contact support.

Messages never include your token, internal traces or database queries.

---

## 400 — Invalid request

### `validation_error` {#validation_error}

The request isn't valid: the body isn't a JSON object, an argument is missing or unexpected, a value has the wrong type, `entity_id` isn't a UUID or was sent in the body, or a URL parameter isn't `true`/`false`. The `detail` says which field failed.

**What to do:** compare the body with the tool's `input_schema` in `GET /v1/tools` or in the [reference](https://docs.clatri.com/en/api/reference/). Don't retry without fixing it.

### `idempotency_key_required` {#idempotency_key_required}

The tool creates, edits or deletes data and the request has no `Idempotency-Key`.

**What to do:** add the header with a unique value per operation (for example, a UUID). If the key has characters that aren't allowed or is longer than 255, the error is `validation_error`.

### `dry_run_not_supported` {#dry_run_not_supported}

You used `?dry_run=true` on a tool that has no preview. Nothing ran.

**What to do:** remove `?dry_run=true`. Only tools with `supports_dry_run: true` in `GET /v1/tools` accept it.

### `https_required` {#https_required}

The request arrived over plain HTTP.

**What to do:** use `https://api.clatri.com/v1`.

---

## 401 — Authentication

Several `401`s in a row can temporarily block the token or the IP (see [`rate_limited`](#rate_limited)).

### `unauthorized` {#unauthorized}

The `Authorization` header is missing, isn't in the form `Bearer <token>`, or the token doesn't exist.

**What to do:** check that you send the full `Authorization: Bearer clt_mcp_…`, without extra spaces.

### `token_revoked` {#token_revoked}

The token was revoked.

**What to do:** create a new one in Settings → Connections → Agents and APIs and replace it in your integration.

### `token_expired` {#token_expired}

The token expired (they last 6 months).

**What to do:** create a new one and replace it.

---

## 402 — Subscription

### `subscription_inactive` {#subscription_inactive}

The Clatri subscription of the token's owner isn't active.

**What to do:** renew it. The same token works again with no changes.

---

## 403 — Permissions

Several `403`s in a row can temporarily block the token or the IP (see [`rate_limited`](#rate_limited)).

### `scope_denied` {#scope_denied}

The token doesn't have the permission the tool requires (for example, it wants to write and the token is read only).

**What to do:** edit the token's permissions in Settings → Connections → Agents and APIs, or use another token.

### `domain_denied` {#domain_denied}

The tool belongs to an area (Money, Health, Administration, General) the token doesn't have.

**What to do:** add the area to the token or use another token.

### `entity_denied` {#entity_denied}

The token can't use the entity in the path, or the body mentions a record (an account, a task…) that belongs to another entity.

**What to do:** check the `entity_id` with `GET /v1/entities` and that the ids in the body belong to that same entity. If you need another entity, add it to the token.

---

## 404 — Not found

### `tool_not_found` {#tool_not_found}

There's no tool with that name.

**What to do:** check the name in `GET /v1/tools`.

### `tool_not_available` {#tool_not_available}

The tool exists but isn't available in the API (access management, credentials, free-form queries, schedules…), or isn't available to this kind of token. See [which tools aren't available](https://docs.clatri.com/en/api/#security).

**What to do:** do that action from the Clatri app or chat.

### `not_found` {#not_found}

The path doesn't exist.

**What to do:** check the URL. The valid paths are in the [guide](https://docs.clatri.com/en/api/#how-it-works).

---

## 405 — Method not allowed

### `method_not_allowed` {#method_not_allowed}

The path exists but not with that method (for example, `GET` on a tool).

**What to do:** tools are called with `POST`; `/v1/me`, `/v1/entities` and `/v1/tools` with `GET`.

---

## 409 — Idempotency conflict

### `idempotency_key_reused` {#idempotency_key_reused}

You already used that `Idempotency-Key` with a different request (another body, tool, entity or parameters). Nothing ran.

**What to do:** generate a new key for each different operation. Reuse a key only to retry exactly the same one.

### `idempotency_in_progress` {#idempotency_in_progress}

A request with that same key is still running.

**What to do:** wait the seconds in `Retry-After` and retry with the same key and the same body. You'll get the result of the first one.

---

## 413 — Body too large

### `payload_too_large` {#payload_too_large}

The body is larger than 256 KB.

**What to do:** split the operation into several calls.

---

## 422 — The tool couldn't complete the request

### `tool_error` {#tool_error}

The request was valid and the tool ran, but it couldn't do what you asked: a record that doesn't exist, insufficient balance, a date out of range… The `detail` explains why with the tool's message.

**What to do:** read the `detail` and fix the data. If you used an `Idempotency-Key`, this result is stored for that key: use a new key for the corrected attempt.

---

## 428 — Confirmation missing

### `confirmation_required` {#confirmation_required}

The tool deletes or cancels data and the URL doesn't include `?confirm=true`. Nothing was deleted.

**What to do:** if you really want to delete, repeat the call with `?confirm=true`.

---

## 429 — Too many requests

### `rate_limited` {#rate_limited}

It happens in two cases:

- **You went over a rate limit:** 120 reads or 30 writes per minute per token, or 300 calls per minute per entity.
- **Temporary block:** 20 `401` or `403` responses within 5 minutes, for the same token or the same IP, block it for 15 minutes.

**What to do:** wait the seconds in `Retry-After` before retrying. If it's a block, first fix the cause of the `401`/`403` responses.

---

## 5xx — Server error

### `internal_error` {#internal_error}

Something failed on our side. If the call had an `Idempotency-Key`, the key is released.

**What to do:** retry later with the same key. If it keeps happening, contact us with the `request_id`.

### `service_unavailable` {#service_unavailable}

A security check (rate limit, idempotency, resource verification) couldn't be completed at that moment. For safety, the call doesn't run.

**What to do:** retry in a few seconds, with the same `Idempotency-Key` if it had one.