Errors | Brain Docs

HTTP client — `BrainHttpError`

Every BrainHttpClient failure throws one error type:

class BrainHttpError extends Error {
  readonly status: number; // HTTP status, or 0 for a transport failure
  readonly code: string;   // stable edge code ("transport" for network failures)
  readonly message: string;
}

ParameterTypeRequired

statusnumberrequired

The HTTP status. 0 means the request never got a response — a transport failure or a client-side timeout (the request was aborted).

codestringrequired

A stable code. When the edge returns a JSON { error: { code, message } } body, that code is used; network failures use "transport"; a config error at construction uses "config".

messagestringrequired

Human-readable detail from the edge, or the transport error message.

import { BrainHttpError } from "@brain-db/sdk";

try {
  await brain.encode({ text: "…" });
} catch (e) {
  if (e instanceof BrainHttpError) {
    if (e.status === 0) console.error("network/timeout:", e.message);
    else console.error(`edge ${e.status} [${e.code}]: ${e.message}`);
  }
}

Only status === 0 (transport/timeout) and status === 503 are retried by the HTTP client, and only for idempotent verbs. See Retries.

Wire client — the `BrainError` hierarchy

Every BrainClient operation rejects with a BrainError or a subclass:

Class	Meaning
`BrainError`	Base class for every client-side failure.
`ProtocolError`	The peer broke the protocol sequence (unexpected opcode, response on an unknown stream).
`ConnectionClosed`	The peer closed the connection.
`BrainTimeout`	An operation missed its deadline. Carries `timeoutMs`.
`VersionMismatch`	The server chose a wire version the client did not offer. Carries `chosen` and `supported`.
`ServerError`	The server returned a structured ERROR frame. Carries `code`, `category`, `retryAfterMs`, and the full `response`.

A corrupt frame throws FrameError from the wire layer — it is fatal for the connection.

ServerError categories

ServerError.category is an ErrorCategoryWire:

Category	Meaning
`Protocol`	Malformed or out-of-sequence request.
`Authentication`	The credential was rejected.
`Authorization`	The identity lacks permission (includes `act_as` denial).
`Validation`	The request failed input validation.
`NotFound`	The referenced entity/memory does not exist.
`Conflict`	Idempotency conflict — same request id, different params.
`ResourceExhausted`	Rate/quota limit — retryable, may carry `retryAfterMs`.
`Internal`	Server-side failure.
`Unavailable`	The shard is temporarily unavailable — retryable.

import { ServerError, ErrorCategoryWire } from "@brain-db/sdk";

try {
  await client.encode(req);
} catch (e) {
  if (e instanceof ServerError && e.category === ErrorCategoryWire.Validation) {
    console.error("bad request:", e.response.message);
  }
}

Classifying failures

Two helpers read the taxonomy so a retry policy can branch:

ParameterTypeRequired

isRetryable(err)booleanrequired

true for a ConnectionClosed, a BrainTimeout, or a ServerError whose category is ResourceExhausted or Unavailable. Malformed-input and auth verdicts are never retryable. This is the signal withRetry consults.

isActAsDenied(err)booleanoptional

true for a ServerError with the ActAsDenied code — the principal lacks the canActAs grant, or the requested act_as namespace is outside its allowlist. Never retryable; the fix is a differently-scoped credential.

HTTP client — BrainHttpError

Wire client — the BrainError hierarchy

ServerError categories

Classifying failures

On this page

HTTP client — `BrainHttpError`

Wire client — the `BrainError` hierarchy