errors
nimblebrain_server_sdk.errors · install nimblebrain-server-sdk · version 0.7.2
from nimblebrain_server_sdk.errors import CapacityRefusal, ErrorCode, HostCapabilityMissingThe errors a server raises and the errors it returns.
HostCapabilityMissing signals a local condition (“this connection cannot carry a
host-resources request”) rather than a wire response. Wire-level errors from the host come
through as mcp.shared.exceptions.MCPError; the SDK does not wrap those, so server code
matches on the JSON-RPC error code through the standard exception path. The other errors the
SDK raises are ValueError and TypeError for a bad argument at registration or call
time, MissingExtraError for a subpackage imported without its extra, and, from the
extras, the errors each documents ([db]’s AuthError, Overloaded,
PoolConfigError and UnsafeRoleError).
The rest is the service error contract: how a server reports a failure that crosses its boundary, so every server fails the same way and no upstream’s internals reach the host.
ServiceErroris the typed failure. Itscodeis one of the closed set inErrorCode, which fixes the HTTP status a host presents and whether a retry can help.messagecrosses to the host and stays generic;detailis for operators and goes to logs only.ServiceError.from_upstreamclassifies a raw upstream HTTP status into that set.to_tool_errorturns aServiceErrorinto the FastMCP tool result toreturn, andrate_limited_tool_errordoes the same for a call refused for capacity.add_error_contract(in the package root) makes a server return either one for aServiceErroror capacity refusal a tool raises, so a tool need not catch them.
Surfacing an error also records it: one service_error log line and one increment of
service_errors_total{service, code, upstream_status}. Both come from
nimblebrain_server_sdk.observability when the [observability] extra is installed.
Without it the tool result is the same, the metric is not recorded, and the log line goes to
the standard library logger nimblebrain_server_sdk.errors. This module imports neither
the extra nor FastMCP until an error is surfaced.
Functions
Section titled “Functions”rate_limited_tool_error
Section titled “rate_limited_tool_error”def rate_limited_tool_error(refusal: CapacityRefusal) -> AnyThe rate_limited tool error for a call refused for capacity, to return.
Classified, counted and logged like any ServiceError. The host sees the refusal’s own
message and what to do next; the code is retryable, and the call ran nothing.
to_tool_error
Section titled “to_tool_error”def to_tool_error(err: ServiceError) -> AnyA real fastmcp.ToolResult(is_error=True) to return from a tool.
Returns the FastMCP result object — NOT a dict. Returning a plain dict does
NOT work: FastMCP scores a returned dict as is_error=False (a success with
the flag buried in structured data), which reproduces the very in-band-error
footgun this contract exists to prevent. The sanitized message is the text
block; structured_content.error carries the envelope.
Imports fastmcp when called, so importing this module does not.
Classes
Section titled “Classes”CapacityRefusal
Section titled “CapacityRefusal”class CapacityRefusal(Protocol)A call refused for capacity before it ran anything, carrying host-safe text.
nimblebrain_server_sdk.db.Overloaded is one; this module names the shape rather than
the class, so it takes no database dependency.
ErrorCode
Section titled “ErrorCode”class ErrorCode(StrEnum)The closed set of cross-cutting error codes.
HostCapabilityMissing
Section titled “HostCapabilityMissing”class HostCapabilityMissing(capability_key: str, *, protocol_version: str | None = None)Raised by a host-resources call the connection cannot carry.
Either the host did not advertise the capability, or the connection negotiated the
2026-07-28 protocol, which has no channel for a request from a server to its client. The
message says which. Catch it, or check host(ctx).available first, and return a tool
error that tells the agent to pass the content inline instead:
try: result = await host(ctx).read(seed_uri)except HostCapabilityMissing: return to_tool_error( ServiceError( ErrorCode.BAD_INPUT, "This connection cannot read workspace files. Pass the file's contents " "in `seed_data` instead.", ) )protocol_version is the negotiated version when the protocol era is the cause, else
None.
ServiceError
Section titled “ServiceError”class ServiceError(code: ErrorCode, message: str | None = None, *, upstream_status: int | None = None, retryable: bool | None = None, detail: str | None = None)A classified, host-safe failure crossing a service boundary.
message crosses the trust boundary to the host — keep it generic; NEVER
put a vendor name/URL, raw upstream body, secret, or tenant data in it.
detail is operator-only (logs); it never reaches the host envelope.
Domain-specific failures subclass this and override metric_code to roll
up to one of the cross-cutting codes for the metric label (so the
service_errors_total{code=...} label stays the closed set).
ServiceError.from_upstream
Section titled “ServiceError.from_upstream”def from_upstream(status: int, message: str | None = None, *, detail: str | None = None) -> ServiceErrorBuild from a raw upstream HTTP status (the common provider-error path).
The bare status number is stamped as host-safe upstream_status; the
vendor’s prose belongs in detail (logs only), never in message.
Omit message to use the classified code’s host-safe default.
ServiceError.metric_code
Section titled “ServiceError.metric_code”metric_code: strThe closed-set code used as the service_errors_total label.
Cross-cutting errors are their own code; domain subclasses override this to roll up, keeping the metric’s label set bounded.
ServiceError.to_envelope
Section titled “ServiceError.to_envelope”def to_envelope() -> dict[str, object]The host-safe error payload (HTTP body / MCP structuredContent.error).