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.
A non-2xx response from POST /v1/<op> has one body shape:
{
"detail": {
"code": "PRECONDITION_FAILED",
"message": "…",
"category": "input",
"retryable": false,
"current_sha256": "…"
}
}-
detail.codenames the failure.detail.messageexplains it. -
detail.categorysays whose move it is, so a caller can act on a code it does not know. Every error with acodecarries it andretryable:categoryMeaning inputThe request does not fit the data or the op as they are now: fix it, or wait when retryablesays they will change.authThe token, its role or its namespace access does not cover the call. capacityThe server or a limit is busy or not ready; the request itself is fine. dependencyA store (Postgres, ClickHouse, the bucket) or a model provider failed, was too slow or is still catching up. configurationThe deployment is not in a state to serve the call; an operator must act. internalThe server failed. Report the request id. -
detail.retryableistruewhen resending the same request unchanged can succeed later with nobody acting, afterretry_after_swhen the error names one. ALOCKEDisfalseeven whenlock_untilnames an end: wait for that time, or for the lock to be lifted, rather than resending on a backoff.falsemeans the same request gets the same answer until something changes. The 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 403auth, 408 and 429capacityand retryable, 502, 503 and 504dependencyand retryable, other 5xxinternal, other 4xxinput). 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
dependencyand retryable, since the caller may be allowed. ForPOLICY_FORBIDDENthis 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, theNAMESPACE_NOT_ACCESSIBLErefusal of a plain namespace and theAUTH_INSUFFICIENTrefusal 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: falseonINTERNAL_ERRORsays the same request is not expected to succeed; Retrying says when one resend of an idempotent op is still reasonable. - 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 (
-
Over MCP, a refusal of a namespace the token may not read (
NAMESPACE_NOT_ACCESSIBLE) carriesnextwhen the namespace is not a collection, the tool is not a code or tracker tool and the connection reachesloom_op: check the name againstnamespace.list_minebefore requesting a grant. A namespace that does not exist gets the same refusal and the same step. -
Some codes add fields to
detail:errorson a validation failure,current_sha256on a precondition failure,retry_after_son the retryable refusals,tableandmigrationonSCHEMA_PENDING,reason(andleft_s) on the assistant's refusals. The table under Common errors names them. -
The
X-Request-Idresponse 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 asrequest_id/requestId. -
An error that carries a retry hint also sets the standard
Retry-Afterheader, so a generic client or proxy can honour it. -
Every error with a
detail.codecarries aLinkheader 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 shows the order in
which the gates that raise these errors run.
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 astructuredContentbody. For a handler's 4xx other than 401 (LOCKED,PINNED_CONFLICT,BLACKLISTED,RESOURCE_NOT_FOUND,RATE_LIMITED,UNKNOWN_ARGUMENT, …) the body is the HTTPdetailplusstatus, andretry_after_swhen the HTTP response would have carriedRetry-After. Every refusal body, these included, carriescategoryandretryableas 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(atools/callwithout a stringnameor with non-objectarguments, 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 HTTPdetailplusstatusinerror.data; any other fault says onlyinternal errorand the request id, withcodeINTERNAL_ERROR. Either wayerror.datacarriescategoryandretryable.
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.
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 and TypeScript SDK.
| 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, 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).
The SDKs' default policy is under Python SDK and TypeScript SDK; the codes they never resend are in each page's Errors section. Each op's kind is in the operations reference.
| 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. |
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). |
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 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. |
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). |
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 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'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. |
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. |
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. |
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. |
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. |
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
LoomServerErrorsubclass underserver/, with its HTTP status (fixed by the class), the class and the first sentence of its docstring. - Other codes: every
"code": "X"dictionary entry andcode="X"keyword argument underserver/that is not a typed error, with the modules that contain it. This catches per-op codes (tracker source registration answersHOST_REFUSED,CREDENTIAL_NOT_READONLYorCONTRACT_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.
Each code below is an anchor: errors.md#<code in lowercase> is the address an HTTP error's Link header names.
Raised in server/memory/app/profile.py.
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.
Raised in server/memory/app/update.py.
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.
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.
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.
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.
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). What to do: common errors.
Raised in server/auth/bearer.py, server/auth/delegation.py, server/auth/login.py. Category auth, retryable: no. What to do: common errors.
Raised in server/auth/bearer.py, server/transport/mcp_auth.py, server/transport/model_maintenance.py, server/transport/tenancy_gate.py.
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.
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.
Raised in server/code/app/repo_admin.py.
Raised in server/memory/app/session_brief.py.
Raised in server/code/app/repo_admin.py.
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.
Raised in server/memory/app/records.py.
Raised in server/memory/app/recall.py.
Raised in server/memory/app/records.py.
Raised in server/memory/app/records.py, server/memory/store/record_query.py.
Raised in server/memory/domain/record_values.py.
Raised in server/tracker/app/sources.py.
Raised in server/code/app/repo_admin.py.
Raised in server/knowledge/app/sources.py.
Raised in server/knowledge/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/knowledge/app/sources.py, server/tracker/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/memory/app/context_offload.py.
Raised in server/code/app/repo_admin.py, server/tracker/app/sources.py.
Raised in server/transport/mcp_refusals.py.
Raised in server/code/app/bisect.py.
Raised in server/code/app/bisect.py, server/code/domain/time_window.py.
Raised in server/memory/app/blacklist_guard.py. What to do: common errors.
Raised in server/memory/app/blacklist.py.
Raised in server/knowledge/app/download_routes.py.
Raised in server/memory/app/promote.py.
Raised in server/memory/app/session_brief.py.
Raised in server/memory/app/session_brief.py.
Raised in server/memory/app/session_brief.py.
Raised in server/memory/app/ops.py.
Raised in server/memory/app/bulk_rows.py, server/memory/app/update.py, server/memory/app/write.py.
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.
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.
Raised in server/transport/model_maintenance.py. Category capacity, retryable: yes.
Raised in server/memory/app/dedup.py.
Raised in server/knowledge/app/dedup.py.
Raised in server/code/app/repo_admin.py, server/knowledge/app/sources.py, server/tracker/app/sources.py.
Raised in server/memory/app/handlers.py.
Raised in server/knowledge/app/conversations.py.
Raised in server/memory/domain/record_values.py.
Raised in server/tracker/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/knowledge/app/sources.py.
Raised in server/main.py.
Raised in server/memory/app/dedup.py.
Raised in server/code/domain/index/repos.py.
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.
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.
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.
Raised in server/memory/app/records.py.
Raised in server/auth/self_signup.py.
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.
Raised in server/memory/store/record_query.py.
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.
Raised in server/memory/domain/record_values.py.
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.
Raised in server/memory/app/update.py.
Raised in server/memory/app/extract/handler.py.
Raised in server/memory/app/extract/handler.py.
Raised in server/memory/app/verify.py.
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.
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.
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.
Raised in server/transport/http.py.
Raised in server/memory/app/promote.py.
Raised in server/tracker/app/sources.py.
Raised in server/transport/http.py, server/transport/mcp_call.py. What to do: common errors.
Raised in server/transport/http.py, server/transport/mcp_call.py. Category capacity, retryable: yes. What to do: common errors.
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.
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.
Raised in server/insights/app/admin_routes.py. Category configuration, retryable: no.
HTTP 500, raised as server.core.errors.LoomServerError. Base class. Category internal, retryable: no.
Raised in server/memory/app/query.py.
Raised in server/auth/self_signup.py.
Raised in server/memory/app/profile.py.
Raised in server/memory/app/query.py.
Raised in server/memory/app/profile.py.
Raised in server/memory/app/write.py.
Raised in server/memory/domain/lock.py. What to do: common errors.
Raised in server/tracker/app/sources.py.
Raised in server/main.py.
Raised in server/memory/app/decision.py, server/memory/app/records.py.
Raised in server/memory/domain/record_values.py.
Raised in server/memory/app/handlers.py.
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.
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.
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.
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.
Raised in server/transport/model_maintenance.py. Category capacity, retryable: yes.
Raised in server/insights/app/provider_activation.py.
Raised in server/auth/self_signup.py.
Raised in server/insights/app/admin_routes.py.
Raised in server/knowledge/app/sources.py.
Raised in server/transport/mcp_auth.py. Category auth, retryable: no; when the check could not run, dependency and yes (the error envelope).
Raised in server/identity/app/claim_release.py, server/insights/app/admin_routes.py.
Raised in server/tracker/app/sources.py.
Raised in server/code/app/index/repo_registry.py, server/code/app/repo_admin.py.
Raised in server/tracker/app/sources.py.
Raised in server/code/app/repo_admin.py.
Raised in server/identity/app/me_service_accounts.py, server/knowledge/app/download_routes.py, server/knowledge/app/writes.py, server/memory/app/blacklist.py.
Raised in server/router/app.py. Category configuration, retryable: no.
Raised in server/knowledge/app/conversations.py.
Raised in server/router/app.py. Category configuration, retryable: no.
Raised in server/knowledge/app/sources.py.
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.
Raised in server/router/app.py. Category input, retryable: no.
Raised in server/transport/mcp_call.py, server/transport/mcp_op.py.
Raised in server/transport/mcp_auth.py. Category auth, retryable: no.
Raised in server/router/app.py. Category input, retryable: no.
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.
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.
Raised in server/auth/login.py.
Raised in server/knowledge/app/sources.py.
Raised in server/memory/app/set_commit.py, server/memory/app/update.py, server/memory/app/write.py. What to do: common errors.
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). What to do: common errors.
HTTP 500, raised as server.core.pg.PostgresRefusedError. 500 — Postgres refused a statement with a data or constraint error. Category internal, retryable: no.
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.
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.
Raised in server/router/app.py. Category capacity, retryable: yes.
Raised in server/router/app.py. Category dependency, retryable: yes.
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.
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.
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.
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.
Raised in server/memory/app/recall.py.
Raised in server/code/app/repo_admin.py.
Raised in server/code/app/repo_admin.py.
Raised in server/code/app/repo_admin.py.
Raised in server/code/app/repo_admin.py.
Raised in server/code/app/repo_admin.py.
Raised in server/memory/app/context_offload.py.
HTTP 404, raised as server.core.errors.NotFoundError. Category input, retryable: no. What to do: common errors.
Raised in server/code/app/repo_admin.py.
Raised in server/identity/app/grants.py, server/identity/app/namespace_membership.py.
Raised in server/code/app/repo_admin.py.
Raised in server/memory/app/records.py.
Raised in server/memory/app/records.py.
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.
Raised in server/memory/app/extract/handler.py.
Raised in server/memory/app/profile.py.
Raised in server/memory/app/profile.py.
Raised in server/code/app/repo_admin.py, server/tracker/app/sources.py.
Raised in server/auth/self_signup.py.
Raised in server/auth/self_signup.py.
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.
Raised in server/memory/app/promote.py.
Raised in server/auth/self_signup.py.
Raised in server/auth/self_signup.py.
Raised in server/auth/self_signup.py.
Raised in server/knowledge/app/sources.py.
Raised in server/knowledge/app/sources.py.
Raised in server/knowledge/app/sources.py, server/tracker/app/sources.py.
Raised in server/tracker/app/sources.py.
Raised in server/knowledge/app/sources.py.
Raised in server/knowledge/app/sources.py.
Raised in server/knowledge/app/sources.py, server/tracker/app/sources.py.
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.
Raised in server/knowledge/app/writes.py.
Raised in server/knowledge/app/sources.py, server/tracker/app/sources.py.
Raised in server/memory/app/profile.py, server/memory/app/working_memory.py.
Raised in server/tasks/app/transitions.py.
Raised in server/tasks/app/transitions.py.
Raised in server/code/app/member_writes.py.
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.
Raised in server/memory/app/curation.py.
Raised in server/identity/app/me_service_accounts.py.
Raised in server/transport/arg_check.py. What to do: common errors.
Raised in server/memory/domain/record_values.py.
Raised in server/memory/app/apply.py, server/memory/app/lock.py, server/memory/app/verify.py.
HTTP 422, raised as server.core.errors.ValidationError. Category input, retryable: no. What to do: common errors.
Raised in server/tracker/app/sources.py.
Raised in server/memory/app/working_memory.py.
Raised in server/memory/app/working_memory.py.
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.
- HTTP API: gates, headers, idempotency and rate limits.
- MCP: how refusals reach a model.
- Unknown and removed fields, including
UNKNOWN_ARGUMENT. - Troubleshooting: operator-side causes of 5xx.