SDK error types (cheat sheet)

The SDK exposes typed Error subclasses so logs and retries can separate client build issues, non-2xx HTTP, SSE protocol issues, and not-yet-implemented APIs.

Overview

ClassTypical caseCommon fields
ContentBuildErrorBuild-time: createRouterBrainFromEnv missing GATEWAY_BASE_URL; fromTurns with paths on assistant/system; env/params violate build rules, etc.message (details per implementation)
GatewayHttpErrorchat.send / files / models (any call) returns non-2xx.status, body
GatewaySseErrorStreaming SSE: upstream error event inside a 200 body.payload
NotImplementedByGatewayErrorRouterBrain stub API not implemented on this HTTP surface.message

GatewaySseError vs GatewayHttpError: the former often surfaces inside for await—wrap stream consumption in try/catch.

Catch example

import {
  ContentBuildError,
  GatewayHttpError,
  GatewaySseError,
  RouterBrain,
  extractTextDelta,
} from "@routerbrain/sdk";

const client = new RouterBrain({ serverURL: process.env.GATEWAY_BASE_URL! });

try {
  const stream = await client.chat.send({
    chatRequest: {
      model: "openai/gpt-4o-mini",
      messages: [{ role: "user", content: "hi" }],
      stream: true,
    },
  });
  for await (const chunk of stream) {
    process.stdout.write(extractTextDelta(chunk));
  }
} catch (e) {
  if (e instanceof GatewayHttpError) {
    console.error("HTTP", e.status, e.body);
  } else if (e instanceof GatewaySseError) {
    console.error("SSE error event", e.payload);
  } else if (e instanceof ContentBuildError) {
    console.error("Client build", e.message);
  } else {
    throw e;
  }
}

Relation to response error.code

GatewayHttpError.body or GatewaySseError.payload may include structured error.code (e.g. invalid_input_file, file_not_found). Full enums and HTTP mapping: deployment docs; index in Troubleshooting.

See also

Back to docs home