Error model

Every non-2xx response is a structured JSON error with a stable field set. The SDKs parse it into a typed exception so you can branch on it programmatically instead of scraping strings.

Fields

Field	Meaning
`status`	HTTP status code (`status_code` in Python)
`type`	Error category (e.g. validation, not-found, auth)
`code`	Stable machine-readable error code
`message`	Human-readable description
`param`	The offending request field, when applicable
`requestId`	Correlation id (`request_id` in Python) — quote it in support requests
`docUrl`	Link to relevant documentation (`doc_url` in Python)

import { LbbError } from "@lbb/client";

try {
  await lbb.graph("main").facts.create({ triplets: [/* … */] });
} catch (err) {
  if (err instanceof LbbError) {
    console.error(err.status, err.code, err.message, err.param, err.requestId, err.docUrl);
    if (err.status === 404) {
      // e.g. the graph or branch doesn't exist
    }
  } else {
    throw err; // network / unexpected
  }
}

from lbb import LbbError

try:
    lbb.graph("main").facts.create({"triplets": [...]})
except LbbError as err:
    print(err.status_code, err.code, err.message, err.param, err.request_id, err.doc_url)
    if err.status_code == 404:
        ...  # graph/branch not found

Common cases

401 / 403 — missing or wrong bearer key, or the key doesn’t own the targeted stack. Check Authorization and that the stack slug matches the key.
404 on a graph/branch — the ?graph=/?branch= you passed doesn’t exist. The MCP server rewrites this raw object-key 404 into an actionable message that lists the tenant’s real graphs (or the graph’s real branches). In the SDKs, list graphs to discover valid names.
Validation errors — param points at the offending field. The typed request shapes (Schemas["…"] in TS, lbb.models.* in Python) catch most of these before you send.
Idempotency conflicts — reusing an idempotency key for a different payload within the retention window is rejected; use a new key for a genuinely new write.

Server-side redaction

5xx responses have their bodies redacted — you get the error envelope and a requestId, not internal detail. Correlate with the requestId (and the /metrics error counters, visible in the console’s Metrics view) when investigating.

MCP boundary

For agents, all LbbError fields survive the MCP boundary in structuredContent.error, so a model can read code/message/param and self-correct its next tool call.