---
title: Errors reference
---

Every refusal Loom makes carries a stable, upper-case `code`. The code is the
contract; the message is for people and can change in any release. Match on
`code`, never on message text.

## The error envelope over HTTP

A non-2xx response from `POST /v1/<op>` has one body shape:

```json
{
  "detail": {
    "code": "PRECONDITION_FAILED",
    "message": "…",
    "category": "input",
    "retryable": false,
    "current_sha256": "…"
  }
}
```

- `detail.code` names the failure. `detail.message` explains it.
- `detail.category` says whose move it is, so a caller can act on a code it does not
  know. Every error with a `code` carries it and `retryable`:

  | `category`      | Meaning                                                                                                              |
  | --------------- | -------------------------------------------------------------------------------------------------------------------- |
  | `input`         | The request does not fit the data or the op as they are now: fix it, or wait when `retryable` says they will change. |
  | `auth`          | The token, its role or its namespace access does not cover the call.                                                 |
  | `capacity`      | The server or a limit is busy or not ready; the request itself is fine.                                              |
  | `dependency`    | A store (Postgres, ClickHouse, the bucket) or a model provider failed, was too slow or is still catching up.         |
  | `configuration` | The deployment is not in a state to serve the call; an operator must act.                                            |
  | `internal`      | The server failed. Report the request id.                                                                            |

- `detail.retryable` is `true` when resending the same request unchanged can succeed
  later with nobody acting, after `retry_after_s` when the error names one. A `LOCKED`
  is `false` even when `lock_until` names an end: wait for that time, or for the lock to
  be lifted, rather than resending on a backoff. `false` means the same request gets the
  same answer until something changes. The [error codes](#error-codes) below state both
  fields for each typed code and each code listed with its own class; the HTTP status
  decides them for the rest (401 and 403 `auth`, 408 and 429 `capacity` and retryable,
  502, 503 and 504 `dependency` and retryable, other 5xx `internal`, other 4xx `input`).
  Two cases set their own:
  - A 5xx from the handler of an op that is not idempotent is never retryable: the call
    may have written. The rule covers the op endpoints (`POST /v1/<op>` and MCP). A route
    outside the registry (sign-in, an admin route, SCIM) is classed by code and status
    alone, so treat a 5xx from a write there as possibly applied.
  - An access refusal whose check could not run (a grant or a history policy's trace
    that could not be read) is `dependency` and retryable, since the caller may be
    allowed. For `POLICY_FORBIDDEN` this is a best guess: a history rule's read can also
    fail the same way every time (a query over a limit), and resending then gets the same
    refusal. Over MCP, the `NAMESPACE_NOT_ACCESSIBLE` refusal of a plain namespace and the
    `AUTH_INSUFFICIENT` refusal on a code or tracker index are the exception: they answer
    the same either way, since a restricted namespace is refused before the read that
    fails, and a different answer would tell it from one that does not exist.

  `retryable: false` on `INTERNAL_ERROR` says the same request is not expected to
  succeed; [Retrying](#retrying) says when one resend of an idempotent op is still
  reasonable.

- Over MCP, a refusal of a namespace the token may not read (`NAMESPACE_NOT_ACCESSIBLE`)
  carries `next` when the namespace is not a collection, the tool is not a code or tracker
  tool and the connection reaches `loom_op`: check the name against `namespace.list_mine`
  before requesting a grant. A namespace that does not exist gets the same refusal and the
  same step.
- Some codes add fields to `detail`: `errors` on a validation failure,
  `current_sha256` on a precondition failure, `retry_after_s` on the retryable
  refusals, `table` and `migration` on `SCHEMA_PENDING`, `reason` (and `left_s`) on the
  assistant's refusals. The table under
  [Common errors](#common-errors-and-what-to-do) names them.
- The `X-Request-Id` response header (echoed from your request when it is 1 to 64
  letters, digits, `.`, `_` or `-`, else a fresh UUID)
  identifies the call on the server's ledger and in its logs. Quote it in a bug
  report; the SDK errors carry it as `request_id` / `requestId`.
- An error that carries a retry hint also sets the standard `Retry-After`
  header, so a generic client or proxy can honour it.
- Every error with a `detail.code` carries a `Link` header to that code's entry in this
  catalogue, `Link: <…/docs/reference/errors.md#pinned_conflict>; rel="help"`
  (`server/core/errors.py`, `error_help_link`), so a client can show where to read about it.

Typed server errors subclass `LoomServerError` (`server/core/errors.py`), whose
`to_detail()` builds this body and whose `headers()` adds `Retry-After` when the
error has `retry_after_s`; `register_exception_handler` turns them into the
response. Handlers that refuse with a FastAPI `HTTPException` use the same
`{"code", "message", …}` detail, so a client sees one shape either way.
[System overview](/docs/ja/architecture/system-overview) shows the order in
which the gates that raise these errors run.

## Errors over MCP

MCP keeps two channels apart, because many clients discard session state on a
JSON-RPC error frame but show a tool result to the model:

- **A call that cannot run as sent is a tool result** with `isError: true`, a
  text block the model reads, and a `structuredContent` body. For a handler's
  4xx other than 401 (`LOCKED`, `PINNED_CONFLICT`, `BLACKLISTED`,
  `RESOURCE_NOT_FOUND`, `RATE_LIMITED`, `UNKNOWN_ARGUMENT`, …) the body is the
  HTTP `detail` plus `status`, and `retry_after_s` when the HTTP response would
  have carried `Retry-After`. Every refusal body, these included, carries `category` and
  `retryable` as over HTTP. Invalid arguments get a message that names each
  field error, each unknown key with the field it most likely meant, the
  required and optional arguments and one corrected example call.
- **Transport failures stay JSON-RPC errors**: parse error `-32700`, invalid
  request `-32600` (an auth refusal carries its HTTP status; a malformed request
  or a batch outside 1 to 64 answers 200), method
  not found `-32601`, invalid params `-32602` (a `tools/call` without a string
  `name` or with non-object `arguments`, an unknown resource), unsupported protocol version `-32022`, and a server fault
  `-32000 "tool execution failed"`. A fault Loom names (`OVERLOADED`,
  `BACKEND_TIMEOUT`, `SCHEMA_PENDING`, `EMBED_TIMEOUT`) puts its code and message in
  that error with the HTTP `detail` plus `status` in `error.data`; any other fault says
  only `internal error` and the request id, with `code` `INTERNAL_ERROR`. Either way
  `error.data` carries `category` and `retryable`.

Codes an op call answers only over MCP: `NAMESPACE_NOT_ACCESSIBLE` (a namespace the token
neither names nor holds a grant on), `ORG_MISMATCH` (an `org` argument the token
may not act in: not its own org, and the token is neither org-wide nor a platform admin's), `UNKNOWN_OP` (`loom_op` named no reachable op; the
result lists near matches with their arguments) and `OP_NOT_ON_MCP` (a hidden
op; the result names what to use instead). See [MCP](/docs/ja/reference/mcp#errors).

## Errors in the SDKs

Both SDKs raise one exception type per family, chosen by `detail.code` and,
when a body carries no code, by HTTP status. Every exception keeps the server's
`code`, the HTTP `status`, the `request_id` and the whole `detail`. A code the
SDK has no class for raises the class its HTTP status maps to (a 409
`PINNED_CONFLICT` is a precondition failure), else the base class with that code
(a 423 `LOCKED`). The class tables are in
[Python SDK](/docs/ja/reference/python-sdk#errors) and [TypeScript SDK](/docs/ja/reference/typescript-sdk#errors).

## Retrying

| Code                        | Status | Retry?                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RATE_LIMITED`              | 429    | Yes, after `Retry-After` (`detail.retry_after_s`). The SDKs pace on the `X-RateLimit-*` headers and wait out a 429 for up to 15 s per call by default.                                                                                                                                                                                                                                                         |
| `OVERLOADED`                | 503    | Yes, after `retry_after_s` (1 s by default), on an idempotent op: a `conversation.delete` or `conversation.compact` resend picks up what the failed call left (a compaction that failed before tombstoning its turns summarises again and replaces the summary it wrote). From the handler of another op it may follow a statement that wrote, so `retryable` is false there.                                  |
| `AUTH_UNAVAILABLE`          | 503    | Yes, after `Retry-After` (5 s). The process has not loaded the token revocation list yet, or, as a [cell](/docs/ja/architecture/cells), has not read its own rows or is configured as its cell's row does not accept, or runs with `LOOM_CELL` unset on a deployment whose cell state gates it (another process behind the same address may serve the call); the op did not run, so the SDKs retry it for any op. |
| `SCHEMA_PENDING`            | 503    | After the migration it names has run. No `Retry-After`: the wait is an operator action, not a timer.                                                                                                                                                                                                                                                                                                           |
| `ANALYSIS_UNAVAILABLE`      | 503    | After the analyst user is written as the allowlist says; `loom doctor` (`analysis_user_failing`) names the fix. A replica whose probe has no answer from ClickHouse, or a ClickHouse short of memory, answers `OVERLOADED` instead.                                                                                                                                                                            |
| `ASSISTANT_UNAVAILABLE`     | 503    | After the assistant can answer in the web process serving the request: no LibreChat is configured (`LOOM_ASSISTANT_LIBRECHAT_URL`), auth is off (an answer is delegated from its caller's token), or this process's setup has not succeeded yet (at boot, or again after LibreChat refused the stored key); `/v1/health` (`assistant_service_failing`) names a setup try that failed.                          |
| `ASSISTANT_UPSTREAM_FAILED` | 503    | Yes, by asking again after `retry_after_s`: LibreChat was unreachable, refused the answer, ended it with an error or ran past its limit. Each answer spends model budget, so the SDKs do not resend one on their own; `retryable` is `true` from the chat route and `false` from the `assistant.ask` op, which is not idempotent, so asking again is the caller's choice.                                      |
| `CODED_WIDTH_MISMATCH`      | 503    | After the embedder and the vector tables agree on a width; `/v1/health` (`coded_width_mismatch`) names the fix. A `memory.set`, `bulk_set`, `update` or `knowledge.*` write left nothing behind.                                                                                                                                                                                                               |
| `TENANCY_REFUSED`           | 503    | No: this cell's Postgres refused a write from a session of this server that lost its tenancy marker; an operator points `LOOM_PG_DSN` straight at Postgres, past any pooler, and `loom doctor` names it.                                                                                                                                                                                                       |
| `GATEWAY_REQUIRED`          | 503    | After a setting moves the call to a listed host: a model call named a host `LOOM_INFERENCE_GATEWAY_HOSTS` does not list while `LOOM_INFERENCE_GATEWAY_REQUIRED` (or a token exchange) is on. The error names the host. A server whose saved model configuration is refused answers every data-plane request with it, naming no host, until a replacement is saved or the configuration is reset.               |
| `EMBED_TIMEOUT`             | 503    | The SDKs retry it for idempotent ops (`memory.search` is one: three attempts by default). A raw HTTP or MCP caller retries once, straight away: the search wrote nothing. If it repeats, the embedding provider is down; back off rather than retry in a loop.                                                                                                                                                 |
| `BACKEND_TIMEOUT`           | 504    | Only an idempotent op, and preferably a narrower request. The statement exceeded its class deadline and the server does not retry it.                                                                                                                                                                                                                                                                          |
| `INTERNAL_ERROR`            | 500    | An idempotent op, once. Report the `request_id` if it repeats.                                                                                                                                                                                                                                                                                                                                                 |
| 4xx other than 429          | 4xx    | No, unless `detail.retryable` says so: a 408 and an access refusal whose check could not run. A `LOCKED` (423) is not retryable: the user lifts the lock, and `lock_until` says when one with an end lapses. Otherwise the same request gets the same answer; fix the request, the token or the data first.                                                                                                    |

`SCHEMA_PENDING`, `ANALYSIS_UNAVAILABLE`, `CODED_WIDTH_MISMATCH`, `GATEWAY_REQUIRED` and
`TENANCY_REFUSED` are 503s because the server cannot serve the request in its current
state, not because the request is wrong; they send no `Retry-After` since only an
operator's fix ends them, and the SDKs never resend an answer the server classes
`configuration`.
`ASSISTANT_UNAVAILABLE` is classed the same and sends no `Retry-After`. It ends on its
own while the web process's setup is still running or retrying (each web process sets
the assistant up on its own, and `/v1/health` reports the process that answers it); no
LibreChat, auth off, or a setup problem whose fix `/v1/health` names needs an operator.
Its `detail.reason` says which: `starting` ends on its own; `failing` is retried by the
process but its fix is named in `/v1/health`; `not_configured` and `auth_off` need an
operator ([the assistant's refusals](/docs/ja/architecture/assistant#the-bridge-each-callers-own-identity)).

The SDKs' default policy is under [Python SDK](/docs/ja/reference/python-sdk#retries-and-logging) and
[TypeScript SDK](/docs/ja/reference/typescript-sdk#retries-pacing-and-logging); the codes they never
resend are in each page's Errors section. Each op's kind is in the
[operations reference](/docs/ja/reference/operations).

## Common errors and what to do

| Code                                | HTTP | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VALIDATION_FAILED`                 | 422  | The body fails the op's input model. `detail.errors` names each field. A body that is not JSON at all is the same code with status 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Read `detail.errors`; check field names and types against the op's schema (`/v1/api/openapi.json`, or `request_fields` in `ops.capabilities`).                                                                                                                                                                                                                                                                                                                                                                                         |
| `UNKNOWN_ARGUMENT`                  | 422  | An op that changes state (any op that is not read-only) got a key that is a near miss for one of its fields (`namepsace`, `tag`). Nothing was written.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Use the field in `did_you_mean`. Read ops serve unknown keys instead and name them in `ignored_args`; see [HTTP API](/docs/ja/reference/http-api#unknown-and-removed-fields).                                                                                                                                                                                                                                                                                                                                                                        |
| `IDENTITY_INCOMPLETE`               | 400  | A namespace-scoped token called without `org` and `namespace`, or a `read_scope` read without the `user_id` / `session_id` it binds to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Put the identity in the body. This is not a permissions failure; the token may be fine.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `AUTH_INVALID`                      | 401  | No bearer where auth is required, a header that is not `Bearer <token>`, or a malformed, expired, revoked or unverifiable token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Mint or fetch a fresh token. A stale `LOOM_API_KEY` in the environment wins over `~/.loom/token`; check which one the client sends.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `AUTH_INSUFFICIENT`                 | 403  | The token's role or namespace access does not cover the op (over MCP the result carries `required_role`). The assistant's refusals carry `reason`: `org_wide`, `narrowed` or `token_expires_soon` with `left_s` ([the assistant's refusals](/docs/ja/architecture/assistant#the-bridge-each-callers-own-identity)).                                                                                                                                                                                                                                                                                                                                                                                 | A namespace that does not exist is refused with the same code as one the token may not read, so check the name against `namespace.list_mine` first. Then compare the op's role in the [operations reference](/docs/ja/reference/operations) with the token (`GET /v1/whoami`) and ask a namespace admin for a grant.                                                                                                                                                                                                                                 |
| `POLICY_FORBIDDEN`                  | 403  | A history-policy rule denied the call (`decision`, `determining_rules`, `errors`) with `LOOM_POLICY_MODE=enforce`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Read `determining_rules`; `errors` tells "denied by policy" from "could not evaluate". See [Tokens and grants](/docs/ja/guides/tokens-and-grants).                                                                                                                                                                                                                                                                                                                                                                                        |
| `RESOURCE_NOT_FOUND`                | 404  | The addressed row, namespace or document does not exist, or is not visible to the caller.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Check the identity tuple and key. Ops addressed only by an org-wide id answer as for a missing row (`found: false`, `updated: false`, `redacted: false`, `removed: false`) when the caller lacks the op's role on the row's namespace, rather than 404, so they never confirm it exists ([row-scoped operations](/docs/ja/architecture/security#row-scoped-operations)).                                                                                                                                                                  |
| `PRECONDITION_FAILED`               | 409  | `if_match_sha256` does not match the live row: another writer changed it. Under the Postgres authority, also an erasure that removed some of a snapshot's memories from the namespace while a `namespace.restore` of it ran.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `detail.current_sha256` is the live hash. Re-read if your change depends on the new value, then resend with that hash; no separate read is needed to retry a blind overwrite. For the restore (no hash), retry it: it leaves out the erased memories.                                                                                                                                                                                                                                                                                  |
| `WRONG_CELL`                        | 409  | The org the call acts in is placed in another [cell](/docs/ja/architecture/cells) of this deployment, or in none and the caller is not scoped to it; nothing was written.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Call the org's cell: `detail.cell` names it when this cell knows where the org is placed ('' otherwise), and `GET /cells/lookup?org=` on the router gives its cell and host; a new org reaches a cell through a request with a token of that org.                                                                                                                                                                                                                                                                                      |
| `PINNED_CONFLICT`                   | 409  | `memory.set` on a key, or close to a fact, that is pinned. A write that does not pin never replaces a pinned memory. `detail.pinned_blocker_id` names the blocking row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Change it with `memory.update` (keeps the pin) or `memory.pin` (re-pins), or store the new fact under its own key.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `IDEMPOTENT_CONFLICT`               | 409  | An `Idempotency-Key` (or MCP `_idempotency_key`) reused with a different body for the same op and caller.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Use a new key per distinct request. Resending the original body with the old key replays the stored answer.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `READS_LLM_FREE`                    | 409  | `memory.ask` or `code.ask` asked for a model's answer while `LOOM_READS_LLM_FREE` is on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Not retried: resending the same request is refused again. Ask with `allow_synthesis=false` / `synthesize=false` for the recalled evidence.                                                                                                                                                                                                                                                                                                                                                                                             |
| `TENANCY_REFUSED`                   | 503  | This [cell](/docs/ja/architecture/cells)'s Postgres refused a row for an org the cell holds no tenancy row for (its org triggers), or a tenancy row (its `loom.tenancy` guard), from a session not marked as one that ran the tenancy check; nothing was written.                                                                                                                                                                                                                                                                                                                                                                                                                                   | If a served request meets it, this process's sessions lost the marker: point `LOOM_PG_DSN` straight at Postgres, past any pooler (`loom doctor` names it); otherwise run the writer as a current Loom with `LOOM_CELL` set.                                                                                                                                                                                                                                                                                                            |
| `IDEMPOTENT_IN_PROGRESS`            | 503  | The first request with this `Idempotency-Key` still runs (on any replica).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Retry after `Retry-After` with the same key and body; the SDKs do. The retry gets the first request's answer.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `BLACKLISTED`                       | 422  | The value matches a refuse pattern registered with `blacklist.add` (`pattern_id`, `scope`, `reason`), or, with an empty `pattern_id`, the request's values are too long to check against the regexes that apply (a short value can be refused once earlier entries spent the budget): send less in one request, or remove regex patterns.                                                                                                                                                                                                                                                                                                                                                        | Do not retry the value. If the pattern is wrong, an admin removes it (`blacklist.remove`). With an empty `pattern_id`, send the value in a smaller request; when the message says to shorten the value, it is too long to check even alone.                                                                                                                                                                                                                                                                                            |
| `LOCKED`                            | 423  | The row carries a `memory.lock` that refuses this write.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Wait for `lock_until` to pass, or have a namespace admin release it with `memory.unlock`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `RATE_LIMITED`                      | 429  | A namespace, org or actor token bucket is empty for the op's class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Wait `Retry-After`. Sustained 429s mean the caller needs pacing or a batch op (`memory.bulk_set`); limits are in [HTTP API](/docs/ja/reference/http-api#rate-limits).                                                                                                                                                                                                                                                                                                                                                                                |
| `OVERLOADED`                        | 503  | Every pooled ClickHouse connection of the serving process stayed busy longer than `LOOM_CH_POOL_WAIT_MS`, a write waited more than 5 s for its org's share of the blacklist's regex threads (refused, not stored unchecked), a budget or rate-limit update waited more than a second for another web process's, or a conversation delete or compaction met concurrent writes to the thread's embeddings for 8 rounds, or `insights.query` ran while the replica's analysis probe had no answer from ClickHouse (5 s). A statement also answers it when ClickHouse is short of the server's or the ClickHouse user's memory, which every query shares (code 241, not a statement's own cap; 5 s). | Retry after `retry_after_s` on an idempotent op; from the handler of another op `retryable` is false, since it may follow a statement that wrote. From `conversation.delete` or `conversation.compact`, the work done so far stays: resend once the thread's writes settle. Repeated across callers, the deployment needs more capacity, has a slow query holding connections or a statement that takes ClickHouse's memory; see [Troubleshooting](/docs/ja/operations/troubleshooting#requests-fail-with-backend_timeout-or-overloaded). |
| `BACKEND_TIMEOUT`                   | 504  | A ClickHouse statement ran past its class deadline (by default reads 30 s, writes 60 s, DDL 300 s: `LOOM_CH_TIMEOUT_READ_S`, `_WRITE_S`, `_DDL_S`); `detail.statement_class` and `timeout_s` say which.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Narrow the request (a smaller `top_k`, a namespace or path filter). Retry only an idempotent op.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `SCHEMA_PENDING`                    | 503  | The call needs a table from a migration this build carries but the database has not applied (`table`, `migration`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | An operator runs `loom migrate` (or restarts with `LOOM_BOOT_MIGRATE=true`); see [Upgrades](/docs/ja/operations/upgrades).                                                                                                                                                                                                                                                                                                                                                                                                                |
| `EMBED_TIMEOUT`                     | 503  | The embedding provider did not answer a search's query embedding within `LOOM_MEMORY_SEARCH_EMBED_BOUND_S` on any attempt (`LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | A raw HTTP or MCP caller retries once; an SDK caller has already retried, so it backs off. Repeated, the provider is slow or down: the log's `query embed exceeded` warnings and `loom.agent_events` rows with this code show it (a hung provider sets no health flag); see [Troubleshooting](/docs/ja/operations/troubleshooting#searches-fail-with-503-embed_timeout).                                                                                                                                                                  |
| `UNKNOWN_OP`, `OP_NOT_ON_MCP` (MCP) | —    | `loom_op` named an op that does not exist or is not reachable on this connection, or a hidden op was called over MCP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Use the suggestion in the result (`did_you_mean`, `instead`), or `loom_op {"op": "help", "query": "<words>"}` to list ops.                                                                                                                                                                                                                                                                                                                                                                                                             |

## How the entries below are generated

`scripts/codegen/docs_reference.py` (`render_errors`) renders one entry per code, headed
by the code so its lowercase form is the anchor the `Link` header names:

- **Typed errors**: every `LoomServerError` subclass under `server/`, with its HTTP
  status (fixed by the class), the class and the first sentence of its docstring.
- **Other codes**: every `"code": "X"` dictionary entry and `code="X"` keyword
  argument under `server/` that is not a typed error, with the modules that
  contain it. This catches per-op codes (tracker source registration answers
  `HOST_REFUSED`, `CREDENTIAL_NOT_READONLY` or `CONTRACT_FAILED`, for example)
  that a hand-written list would miss. Because the scan is syntactic, it also
  lists a few codes the server records on its own ledger rather than sending
  (`HANDLER_HTTP_ERROR`), and codes answered outside the op endpoints (sign-up,
  OAuth, admin routes).
- A code the "Common errors" table above covers links back to it.

Each op documents its own codes in its description; they all use the envelope
above.

## Error codes

<!-- BEGIN GENERATED: errors -->
<!-- Generated by `python scripts/codegen/docs_reference.py`; edit the source, not this region. -->
<!-- prettier-ignore-start -->

Each code below is an anchor: `errors.md#<code in lowercase>` is the address an HTTP error's `Link` header names.

#### `ACTIVITY_UNAVAILABLE`

Raised in `server/memory/app/profile.py`.

#### `ADMISSION_CONTENDED`

HTTP 503, raised as `server.memory.store.pg_memory.AdmissionContendedError`. 503 — commits kept landing in this write's scope faster than it could re-check against them. Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran.

#### `AMBIGUOUS_KEY`

Raised in `server/memory/app/update.py`.

#### `ANALYSIS_UNAVAILABLE`

HTTP 503, raised as `server.core.errors.AnalysisUnavailableError`. `insights.query` cannot run on this replica: the probe each process runs on an interval found, or a statement's login met, the analyst ClickHouse user missing, wider than the allowlist, or refusing… Category `configuration`, retryable: no.

#### `ASSISTANT_SELF_CALL`

HTTP 403, raised as `server.core.errors.AssistantSelfCallError`. An assistant answer's own token, or a token delegated from one, asked the assistant: the assistant never calls itself (docs/architecture/assistant.md). Category `auth`, retryable: no.

#### `ASSISTANT_UNAVAILABLE`

HTTP 503, raised as `server.core.errors.AssistantUnavailableError`. The assistant cannot answer in this web process: no LibreChat is configured (`LOOM_ASSISTANT_LIBRECHAT_URL`), auth is off (an answer is delegated from its caller's token), or this process's setup has… Category `configuration`, retryable: no.

#### `ASSISTANT_UPSTREAM_FAILED`

HTTP 503, raised as `server.core.errors.AssistantUpstreamError`. LibreChat could not give this answer: it was unreachable, refused the request, ended the answer with an error, or ran past the answer's limit. Category `dependency`, retryable: yes for an idempotent op, no for another op once it ran.

#### `AUTH_INSUFFICIENT`

HTTP 403, raised as `server.core.errors.AuthInsufficientError`. A public 403 that remains catchable as ``PermissionError`` internally. Category `auth`, retryable: no; when the check could not run, `dependency` and yes ([the error envelope](#the-error-envelope-over-http)). What to do: [common errors](#common-errors-and-what-to-do).

#### `AUTH_INVALID`

Raised in `server/auth/bearer.py`, `server/auth/delegation.py`, `server/auth/login.py`, `server/transport/tenancy_gate.py`. Category `auth`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `AUTH_UNAVAILABLE`

Raised in `server/auth/bearer.py`, `server/transport/mcp_auth.py`, `server/transport/model_maintenance.py`, `server/transport/tenancy_gate.py`.

#### `BACKEND_TIMEOUT`

HTTP 504, raised as `server.core.errors.BackendTimeoutError`. 504 — a ClickHouse statement ran past its class deadline (reads 30 s, writes 60 s, DDL 300 s). Category `dependency`, retryable: yes for an idempotent op, no for another op once it ran. What to do: [common errors](#common-errors-and-what-to-do).

#### `BACKEND_UNAVAILABLE`

HTTP 503, raised as `server.core.errors.BackendUnavailableError`. 503 — ClickHouse, the document bucket, or a cell's tenancy read or placement failed; the router's lookup and operator API send the code when their directory fails. Category `dependency`, retryable: yes for an idempotent op, no for another op once it ran.

#### `BAD_BRANCH`

Raised in `server/code/app/repo_admin.py`.

#### `BAD_BRIEF_KEY`

Raised in `server/memory/app/session_brief.py`.

#### `BAD_CLASSIFICATION`

Raised in `server/code/app/repo_admin.py`.

#### `BAD_CONFIG`

HTTP 422, raised as `server.core.errors.BadConfigError`. 422 — a document source's config or items it cannot use, or a change it cannot make; the message, Loom's own, names what to fix. Category `input`, retryable: no.

#### `BAD_CONSTRAINT`

Raised in `server/memory/app/records.py`.

#### `BAD_CURSOR`

Raised in `server/memory/app/recall.py`.

#### `BAD_ENUM_FIELD`

Raised in `server/memory/app/records.py`.

#### `BAD_FIELD_NAME`

Raised in `server/memory/app/records.py`, `server/memory/store/record_query.py`.

#### `BAD_FIELD_VALUE`

Raised in `server/memory/domain/record_values.py`.

#### `BAD_INPUT`

Raised in `server/tracker/app/sources.py`.

#### `BAD_JOIN_POLICY`

Raised in `server/code/app/repo_admin.py`.

#### `BAD_KIND`

Raised in `server/knowledge/app/sources.py`.

#### `BAD_LINK`

Raised in `server/knowledge/app/sources.py`.

#### `BAD_MAPPING`

Raised in `server/tracker/app/sources.py`.

#### `BAD_NAME`

Raised in `server/knowledge/app/sources.py`, `server/tracker/app/sources.py`.

#### `BAD_NAMESPACE`

Raised in `server/tracker/app/sources.py`.

#### `BAD_ORG`

Raised in `server/tracker/app/sources.py`.

#### `BAD_PATTERN`

Raised in `server/memory/app/context_offload.py`.

#### `BAD_REPO`

Raised in `server/code/app/repo_admin.py`, `server/tracker/app/sources.py`.

#### `BAD_REQUEST`

Raised in `server/transport/mcp_refusals.py`.

#### `BAD_SHA`

Raised in `server/code/app/bisect.py`.

#### `BAD_TIME`

Raised in `server/code/app/bisect.py`, `server/code/domain/time_window.py`.

#### `BLACKLISTED`

Raised in `server/memory/app/blacklist_guard.py`. What to do: [common errors](#common-errors-and-what-to-do).

#### `BLACKLIST_PATTERN_INVALID`

Raised in `server/memory/app/blacklist.py`.

#### `BLOB_GONE`

Raised in `server/knowledge/app/download_routes.py`, `server/knowledge/app/source_downloads.py`.

#### `BLOCK_PROMOTION_REFUSED`

Raised in `server/memory/app/promote.py`.

#### `BRIEF_KEY_REQUIRED`

Raised in `server/memory/app/session_brief.py`.

#### `BRIEF_REVISION_MISMATCH`

Raised in `server/memory/app/session_brief.py`.

#### `BRIEF_SELECTOR_REQUIRED`

Raised in `server/memory/app/session_brief.py`.

#### `CATEGORY_NOT_FOUND`

Raised in `server/memory/app/ops.py`.

#### `CHAR_LIMIT_EXCEEDED`

Raised in `server/memory/app/bulk_rows.py`, `server/memory/app/update.py`, `server/memory/app/write.py`.

#### `CODED_WIDTH_MISMATCH`

HTTP 503, raised as `server.core.errors.CodedWidthMismatchError`. 503 — a vector in the write is not the width its `Quantized` column was created at, so ClickHouse would refuse the insert. Category `configuration`, retryable: no.

#### `COLLECTION_NAME_TAKEN`

HTTP 409, raised as `server.core.errors.CollectionNameTakenError`. 409 — no name could be had: the one asked for is used or was a deleted collection's (`deleted`), or every name a title derives is taken; `suggestion` is a free name when one was found, else ''. Category `input`, retryable: no.

#### `CONFIG_DRIFT`

Raised in `server/transport/model_maintenance.py`. Category `capacity`, retryable: yes.

#### `CONFIRM_CANONICAL_KEY_MISMATCH`

Raised in `server/memory/app/dedup.py`.

#### `CONFIRM_DUPLICATE_URI_MISMATCH`

Raised in `server/knowledge/app/dedup.py`.

#### `CONFIRM_REQUIRED`

Raised in `server/code/app/repo_admin.py`, `server/knowledge/app/sources.py`, `server/tracker/app/sources.py`.

#### `CONFIRM_SUBJECT_MISMATCH`

Raised in `server/memory/app/handlers.py`.

#### `CONFIRM_THREAD_ID_MISMATCH`

Raised in `server/knowledge/app/conversations.py`.

#### `CONNECTION_UNAVAILABLE`

Raised in `server/knowledge/app/connected_accounts.py`.

#### `CONSTRAINT_VIOLATION`

Raised in `server/memory/domain/record_values.py`.

#### `CONTRACT_FAILED`

Raised in `server/tracker/app/sources.py`.

#### `CONTROL_UPGRADE_REQUIRED`

Raised in `server/router/app.py`.

#### `CREDENTIAL_NOT_READONLY`

Raised in `server/tracker/app/sources.py`.

#### `CREDENTIAL_READONLY_MODE`

Raised in `server/tracker/app/sources.py`.

#### `CREDENTIAL_REFUSED`

Raised in `server/knowledge/app/connected_sources.py`, `server/knowledge/app/sources.py`.

#### `CROSS_SITE_REQUEST`

Raised in `server/main.py`.

#### `DEDUP_PAIR_NOT_FOUND`

Raised in `server/memory/app/dedup.py`.

#### `DEFAULT_NAMESPACE_REFUSED`

Raised in `server/code/domain/index/repos.py`.

#### `DEFINITION_CEILING`

HTTP 409, raised as `server.core.errors.DefinitionCeilingError`. 409 — the promotion would leave the namespace past `memory_shared_definitions_max` shared definitions: at the ceiling, demote one to add a new key; past it, demote until at most that many remain. Category `input`, retryable: no.

#### `DEFINITION_NAME_TAKEN`

HTTP 409, raised as `server.core.errors.DefinitionNameTakenError`. 409 — another shared definition holds this term or an alias; `conflicting_keys` names those definitions and `names` the folded names they hold. Category `input`, retryable: no.

#### `DEFINITION_PROMOTION_REFUSED`

HTTP 422, raised as `server.core.errors.DefinitionPromotionRefusedError`. 422 — a definition is promoted only from its live namespace-wide row under a `definition/` key, to that same key, and a row of another type is never promoted under a `definition/` key. Category `input`, retryable: no.

#### `DUPLICATE_FIELD`

Raised in `server/memory/app/records.py`.

#### `EMAIL_IN_USE`

Raised in `server/auth/self_signup.py`.

#### `EMBED_TIMEOUT`

HTTP 503, raised as `server.core.errors.EmbedTimeoutError`. 503 — the query embedding did not answer within `memory_search_embed_bound_s` on any attempt. Category `dependency`, retryable: yes for an idempotent op, no for another op once it ran. What to do: [common errors](#common-errors-and-what-to-do).

#### `EMPTY_PREDICATE`

Raised in `server/memory/store/record_query.py`.

#### `ENTRY_LEASE_NOT_HELD`

HTTP 409, raised as `server.code.app.ingest.EntryLeaseNotHeld`. The pass that built this upload no longer holds its entry's lease: another pass may be indexing the entry, so its batch must not complete. Category `input`, retryable: no.

#### `ENUM_VIOLATION`

Raised in `server/memory/domain/record_values.py`.

#### `ERASURE_RUNNING`

HTTP 409, raised as `server.core.errors.ErasureRunningError`. 409 — an erasure that will still run covers the namespace: a document source added or updated now would outlast it, since its first step may already have read the namespace's sources. Category `capacity`, retryable: yes.

#### `EXPIRED`

Raised in `server/memory/app/update.py`.

#### `EXTRACTION_FAILED`

Raised in `server/memory/app/extract/handler.py`.

#### `EXTRACTION_QUEUE_UNAVAILABLE`

Raised in `server/memory/app/extract/handler.py`.

#### `FORBIDDEN`

Raised in `server/memory/app/verify.py`.

#### `GATEWAY_REQUIRED`

HTTP 503, raised as `server.core.errors.GatewayRequiredError`. 503 — a model call named a host LOOM_INFERENCE_GATEWAY_HOSTS does not list while the gateway is required (`LOOM_INFERENCE_GATEWAY_REQUIRED`, or a workload token); the message names the host. Category `configuration`, retryable: no.

#### `GRANT_BUSY`

HTTP 503, raised as `server.core.errors.GrantBusyError`. 503 — another change to the same grant held it past the wait. Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran.

#### `GRANT_WOULD_DOWNGRADE`

HTTP 409, raised as `server.core.errors.GrantWouldDowngradeError`. 409 — `grants.create` asked for a role below the subject's current active grant on that namespace. Category `input`, retryable: no.

#### `HANDLER_HTTP_ERROR`

Raised in `server/transport/http.py`.

#### `HIGH_SENSITIVITY_PROMOTION_REFUSED`

Raised in `server/memory/app/promote.py`.

#### `HOST_REFUSED`

Raised in `server/tracker/app/sources.py`.

#### `IDEMPOTENT_CONFLICT`

Raised in `server/transport/http.py`, `server/transport/mcp_call.py`. What to do: [common errors](#common-errors-and-what-to-do).

#### `IDEMPOTENT_IN_PROGRESS`

Raised in `server/transport/http.py`, `server/transport/mcp_call.py`. Category `capacity`, retryable: yes. What to do: [common errors](#common-errors-and-what-to-do).

#### `IDEMPOTENT_TAKEN_OVER`

HTTP 503, raised as `server.memory.store.pg_memory.IdempotencyFenced`. 503 — this request's idempotency claim is no longer its own: a retry with the key took it over, or an erasure in the org fenced it. Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran.

#### `IDENTITY_INCOMPLETE`

HTTP 400, raised as `server.core.errors.IdentityIncompleteError`. A scoped token was presented without org+namespace in the request body. Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `INTEGRATION_NOT_CONFIGURED`

Raised in `server/insights/app/admin_routes.py`. Category `configuration`, retryable: no.

#### `INTERNAL_ERROR`

HTTP 500, raised as `server.core.errors.LoomServerError`. Base class. Category `internal`, retryable: no.

#### `INVALID_AGG`

Raised in `server/memory/app/query.py`.

#### `INVALID_EMAIL`

Raised in `server/auth/self_signup.py`.

#### `INVALID_FORMAT`

Raised in `server/memory/app/profile.py`.

#### `INVALID_IDENTIFIER`

Raised in `server/memory/app/query.py`.

#### `INVALID_SCOPE`

Raised in `server/memory/app/profile.py`.

#### `KEY_HOLDS_FACT`

Raised in `server/memory/app/write.py`.

#### `LOCKED`

Raised in `server/memory/domain/lock.py`. What to do: [common errors](#common-errors-and-what-to-do).

#### `MAPPING_FAILED`

Raised in `server/tracker/app/sources.py`.

#### `MISDIRECTED_REQUEST`

Raised in `server/main.py`.

#### `MISSING_IDENTITY_FIELD`

Raised in `server/memory/app/decision.py`, `server/memory/app/records.py`.

#### `MISSING_REQUIRED_FIELD`

Raised in `server/memory/domain/record_values.py`.

#### `MISSING_SCOPE`

Raised in `server/memory/app/handlers.py`.

#### `MODEL_CALLS_DISABLED`

HTTP 403, raised as `server.llm.customer.ModelCallsDisabled`. The org's admin switched its model calls off: nothing is sent for it. Category `configuration`, retryable: no.

#### `MODEL_CALL_DEFERRED`

HTTP 503, raised as `server.core.errors.ModelCallDeferred`. 503 — the inference gateway asked the call's identity to wait for `retry_after_s`, its `Retry-After`. Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran.

#### `MODEL_CALL_REFUSED`

HTTP 403, raised as `server.core.errors.ModelCallRefused`. 403 — the inference gateway refused the call for the identity it was made for: that identity's refusal, not the provider's failure. Category `auth`, retryable: no.

#### `MODEL_CALL_UNATTRIBUTED`

HTTP 500, raised as `server.llm.customer.Unattributed`. A model call with no customer to bill: a caller that set none (a job that did not name the org of its rows). Category `internal`, retryable: no.

#### `MODEL_CHANGE_IN_PROGRESS`

Raised in `server/transport/model_maintenance.py`. Category `capacity`, retryable: yes.

#### `MODEL_VALIDATION_FAILED`

Raised in `server/insights/app/provider_activation.py`.

#### `NAMESPACE_CLAIMED`

Raised in `server/auth/self_signup.py`.

#### `NAMESPACE_HAS_ADMIN`

Raised in `server/insights/app/admin_routes.py`.

#### `NAMESPACE_INACTIVE`

Raised in `server/knowledge/app/sources.py`.

#### `NAMESPACE_NOT_ACCESSIBLE`

Raised in `server/transport/mcp_auth.py`. Category `auth`, retryable: no; when the check could not run, `dependency` and yes ([the error envelope](#the-error-envelope-over-http)).

#### `NAMESPACE_NOT_FOUND`

Raised in `server/identity/app/claim_release.py`, `server/insights/app/admin_routes.py`.

#### `NAMESPACE_TAKEN`

Raised in `server/tracker/app/sources.py`.

#### `NOT_A_REPO`

Raised in `server/code/app/index/repo_registry.py`, `server/code/app/repo_admin.py`.

#### `NOT_A_SOURCE`

Raised in `server/tracker/app/sources.py`.

#### `NOT_A_TRACKER_NAMESPACE`

Raised in `server/code/app/repo_admin.py`.

#### `NOT_FOUND`

Raised in `server/identity/app/me_service_accounts.py`, `server/knowledge/app/download_routes.py`, `server/knowledge/app/source_downloads.py`, `server/knowledge/app/writes.py`, `server/memory/app/blacklist.py`.

#### `NO_CELL`

Raised in `server/router/app.py`. Category `configuration`, retryable: no.

#### `NO_FIELDS_PROVIDED`

Raised in `server/knowledge/app/conversations.py`.

#### `NO_OPERATOR_CREDENTIAL`

Raised in `server/router/app.py`. Category `configuration`, retryable: no.

#### `NO_ROOT_SECRET`

Raised in `server/knowledge/app/sources.py`.

#### `NO_SIGNING_KEY`

HTTP 503, raised as `server.auth.keyring.NoSigningKey`. Kid `default` is retired (or the root secret signs neither HS256 nor RS256) and no keyring key is active here: nothing can be signed until an operator acts, so it carries no Retry-After. Category `configuration`, retryable: no.

#### `NO_SUCH_CELL`

Raised in `server/router/app.py`. Category `input`, retryable: no.

#### `OP_NOT_ON_MCP`

Raised in `server/transport/mcp_call.py`, `server/transport/mcp_op.py`.

#### `ORG_MISMATCH`

Raised in `server/transport/mcp_auth.py`. Category `auth`, retryable: no.

#### `ORG_TOO_LONG`

Raised in `server/router/app.py`. Category `input`, retryable: no.

#### `OVERLOADED`

HTTP 503, raised as `server.core.errors.OverloadedError`. 503 — too busy, retry: the ClickHouse pool or its streams, ClickHouse's shared memory, the document bucket's transfers or streams, an override's lock, a namespace's document-source lease or… Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran. What to do: [common errors](#common-errors-and-what-to-do).

#### `OVERRIDE_NOT_STORED`

HTTP 409, raised as `server.core.runtime_overrides.OverrideNotStoredError`. 409 — ClickHouse refused to store the override (a read-only user, for example), so no process changed; the server log has the reason. Category `configuration`, retryable: no.

#### `PASSWORD_LOGIN_SSO`

Raised in `server/auth/login.py`.

#### `PERSONAL_NAMESPACE`

Raised in `server/knowledge/app/sources.py`.

#### `PINNED_CONFLICT`

Raised in `server/memory/app/set_commit.py`, `server/memory/app/update.py`, `server/memory/app/write.py`. What to do: [common errors](#common-errors-and-what-to-do).

#### `POLICY_FORBIDDEN`

HTTP 403, raised as `server.identity.app.policy_gate.PolicyForbiddenError`. 403 with the decision attached: which rules denied, per-leaf values, and any evaluation errors — "denied by policy" and "denied because the check could not run" are distinguishable by `errors`. Category `auth`, retryable: no; when the check could not run, `dependency` and yes ([the error envelope](#the-error-envelope-over-http)). What to do: [common errors](#common-errors-and-what-to-do).

#### `POSTGRES_REFUSED`

HTTP 500, raised as `server.core.pg.PostgresRefusedError`. 500 — Postgres refused a statement with a data or constraint error. Category `internal`, retryable: no.

#### `POSTGRES_UNAVAILABLE`

HTTP 503, raised as `server.core.pg.PostgresUnavailableError`. 503 — Postgres, the memory authority, could not answer. Category `dependency`, retryable: yes for an idempotent op, no for another op once it ran.

#### `PRECONDITION_FAILED`

HTTP 409, raised as `server.core.errors.PreconditionFailedError`. 409 — `if_match_sha256` mismatch, an `approved_sha256` that no longer matches the definition's text, or an erasure that landed while a `namespace.restore` ran. Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `PROBE_BUSY`

Raised in `server/router/app.py`. Category `capacity`, retryable: yes.

#### `PROBE_UNREACHABLE`

Raised in `server/router/app.py`. Category `dependency`, retryable: yes.

#### `PROCESS_STOPPING`

Raised in `server/transport/model_maintenance.py`, `server/transport/retirement.py`.

#### `PROJECTION_BEHIND`

HTTP 503, raised as `server.memory.app.pg_admission.ProjectionBehindError`. 503 — earlier commits in this namespace are not yet in ClickHouse, so a read of ClickHouse that must see every write the namespace committed would miss them. Category `capacity`, retryable: yes for an idempotent op, no for another op once it ran.

#### `PUBLICATION_PENDING`

HTTP 503, raised as `server.core.pg_lease.PublicationPending`. 503: the write is committed and the delivery worker publishes its rows; it is not to be made again. Category `dependency`, retryable: no.

#### `RATE_LIMITED`

HTTP 429, raised as `server.core.errors.RateLimitedError`. 429 — the caller is over one of its admission limits (the org's in-flight requests); `retry_after_s` is the hint the SDK's retry layer honours. Category `capacity`, retryable: yes. What to do: [common errors](#common-errors-and-what-to-do).

#### `READS_LLM_FREE`

HTTP 409, raised as `server.core.errors.ReadsLlmFreeError`. 409 — `memory.ask` or `code.ask` asked for a model's answer while `LOOM_READS_LLM_FREE` is on. Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `RECALL_REQUIRES_FILTER`

Raised in `server/memory/app/recall.py`.

#### `REMOTE_REFUSED`

Raised in `server/code/app/repo_admin.py`.

#### `REPO_EXISTS`

Raised in `server/code/app/repo_admin.py`.

#### `REPO_FROM_CONFIG`

Raised in `server/code/app/repo_admin.py`.

#### `REPO_NOT_INDEXED`

Raised in `server/code/app/repo_admin.py`.

#### `REPO_QUOTA`

Raised in `server/code/app/repo_admin.py`.

#### `REQUEST_INTERRUPTED`

Raised in `server/observability/ledger.py`.

#### `RESERVED_BLOB_KEY`

Raised in `server/memory/app/context_offload.py`.

#### `RESOURCE_NOT_FOUND`

HTTP 404, raised as `server.core.errors.NotFoundError`. Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `RESTRICTED_NOT_OPEN`

Raised in `server/code/app/repo_admin.py`.

#### `ROLE_CEILING`

Raised in `server/identity/app/grants.py`, `server/identity/app/namespace_membership.py`.

#### `SANDBOX_UNAVAILABLE`

Raised in `server/code/app/repo_admin.py`.

#### `SCHEMA_ACTIVE`

Raised in `server/memory/app/records.py`.

#### `SCHEMA_NOT_FOUND`

Raised in `server/memory/app/records.py`.

#### `SCHEMA_PENDING`

HTTP 503, raised as `server.core.errors.SchemaPendingError`. 503 — the statement names a table that a migration this build carries but the service has not applied would create. Category `configuration`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `SCHEMA_REQUIRES_KEY`

Raised in `server/memory/app/extract/handler.py`.

#### `SECTION_NOT_FOUND`

Raised in `server/memory/app/profile.py`.

#### `SECTION_NOT_STRING`

Raised in `server/memory/app/profile.py`.

#### `SELF_SERVICE_OFF`

Raised in `server/code/app/repo_admin.py`, `server/tracker/app/sources.py`.

#### `SELF_SIGNUP_DISABLED`

Raised in `server/auth/self_signup.py`.

#### `SELF_SIGNUP_SSO`

Raised in `server/auth/self_signup.py`.

#### `SENSITIVE_DEFINITION_REFUSED`

HTTP 422, raised as `server.core.errors.SensitiveDefinitionRefusedError`. 422 — a definition labelled `medium`, or whose value reads as `medium` or `high`, is not promoted: the shared layer serves it to every reader of the namespace. Category `input`, retryable: no.

#### `SESSION_PROTECTION_REQUIRED`

HTTP 409, raised as `server.core.errors.SessionProtectionRequiredError`. 409 — session-content operations need the client's protection promise. Category `configuration`, retryable: no.

#### `SHARED_CONFLICT`

Raised in `server/memory/app/promote.py`.

#### `SIGNUP_IN_PROGRESS`

Raised in `server/auth/self_signup.py`.

#### `SIGNUP_ORG_FIXED`

Raised in `server/auth/self_signup.py`.

#### `SIGNUP_UNAVAILABLE`

Raised in `server/auth/self_signup.py`.

#### `SOURCE_DELETE_PENDING`

Raised in `server/knowledge/app/sources.py`.

#### `SOURCE_DOCUMENTS_KEPT`

Raised in `server/knowledge/app/sources.py`.

#### `SOURCE_EXISTS`

Raised in `server/knowledge/app/sources.py`, `server/tracker/app/sources.py`.

#### `SOURCE_FROM_CONFIG`

Raised in `server/tracker/app/sources.py`.

#### `SOURCE_NOT_FOUND`

Raised in `server/knowledge/app/sources.py`.

#### `SOURCE_NOT_SERVED`

Raised in `server/knowledge/app/sources.py`.

#### `SOURCE_QUOTA`

Raised in `server/knowledge/app/sources.py`, `server/tracker/app/sources.py`.

#### `SOURCE_REPLACED`

HTTP 409, raised as `server.core.errors.SourceReplacedError`. 409 — the document source was removed and added again as another source during the call (an update's or a rotate's probe, a sync request); act on the current one. Category `input`, retryable: no.

#### `SOURCE_TAGS_LOCKED`

Raised in `server/knowledge/app/writes.py`.

#### `SOURCE_UNREACHABLE`

Raised in `server/knowledge/app/sources.py`, `server/tracker/app/sources.py`.

#### `SUBSTRING_NOT_FOUND`

Raised in `server/memory/app/profile.py`, `server/memory/app/working_memory.py`.

#### `TASK_NOT_BLOCKABLE`

Raised in `server/tasks/app/transitions.py`.

#### `TASK_NOT_DEFERRABLE`

Raised in `server/tasks/app/transitions.py`.

#### `TEAM_RULE_NOT_YOURS`

Raised in `server/code/app/member_writes.py`.

#### `TENANCY_REFUSED`

HTTP 503, raised as `server.core.errors.TenancyRefusedError`. 503 — this cell's Postgres refused a row for an org the cell holds no tenancy row for (its org triggers), or a tenancy row (its `loom.tenancy` guard; docs/architecture/cells.md): the session that… Category `configuration`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `TIMELINE_REQUIRES_FILTER`

Raised in `server/memory/app/curation.py`.

#### `TOKEN_NAME_TAKEN`

Raised in `server/identity/app/me_service_accounts.py`.

#### `UNKNOWN_ARGUMENT`

Raised in `server/transport/arg_check.py`. What to do: [common errors](#common-errors-and-what-to-do).

#### `UNKNOWN_FIELD`

Raised in `server/memory/domain/record_values.py`.

#### `VALIDATION`

Raised in `server/memory/app/apply.py`, `server/memory/app/lock.py`, `server/memory/app/verify.py`.

#### `VALIDATION_FAILED`

HTTP 422, raised as `server.core.errors.ValidationError`. Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

#### `VECTOR_INPUT_TOO_LARGE`

HTTP 422, raised as `server.core.errors.VectorInputTooLargeError`. 422 — an entity filter exceeds 64 raw names, or its canonical aliases or summary seeds exceed 256 distinct names. Category `input`, retryable: no.

#### `VIEWS_NOT_READABLE`

Raised in `server/tracker/app/sources.py`.

#### `WORKING_MEMORY_BLOCK_NOT_FOUND`

Raised in `server/memory/app/working_memory.py`.

#### `WORKING_MEMORY_LIMIT_EXCEEDED`

Raised in `server/memory/app/working_memory.py`.

#### `WRONG_CELL`

HTTP 409, raised as `server.core.errors.WrongCellError`. 409 — the org a verified call acts in is placed in another cell of this deployment, or in none and the caller may not place it (docs/architecture/cells.md). Category `input`, retryable: no. What to do: [common errors](#common-errors-and-what-to-do).

<!-- prettier-ignore-end -->
<!-- END GENERATED: errors -->

## Related

- [HTTP API](/docs/ja/reference/http-api): gates, headers, idempotency and rate limits.
- [MCP](/docs/ja/reference/mcp#errors): how refusals reach a model.
- [Unknown and removed fields](/docs/ja/reference/http-api#unknown-and-removed-fields), including `UNKNOWN_ARGUMENT`.
- [Troubleshooting](/docs/ja/operations/troubleshooting): operator-side causes of 5xx.
