Skip to main content

API errors

When a call to the Clatri API fails, the response is application/problem+json (RFC 9457):

{
  "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​

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. Don't retry without fixing it.

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​

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​

The request arrived over plain HTTP.

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

401 — Authentication​

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

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​

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​

The token expired (they last 6 months).

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

402 — Subscription​

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 403s in a row can temporarily block the token or the IP (see rate_limited).

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​

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​

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​

There's no tool with that name.

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

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.

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

not_found​

The path doesn't exist.

What to do: check the URL. The valid paths are in the guide.

405 — 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​

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​

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​

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​

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​

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​

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​

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​

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.