Errors
nimblebrain_server_sdk.errors is the contract a server reports a failure with, so every server fails the same way and nothing internal to it or to a service it calls reaches the host. It is in the core package: no extra is needed.
Raise it, or return it
Section titled “Raise it, or return it”With add_error_contract(mcp) called once, a tool raises a ServiceError and the caller receives the contract’s result:
from nimblebrain_server_sdk import READS, add_error_contractfrom nimblebrain_server_sdk.errors import ErrorCode, ServiceError
add_error_contract(mcp)
@mcp.tool(annotations=READS)async def search(query: str) -> list[dict[str, str]]: if not query.strip(): raise ServiceError(ErrorCode.BAD_INPUT, "`query` is empty.") try: return await provider.search(query) except ProviderError as exc: # carries the upstream's HTTP status raise ServiceError.from_upstream(exc.status, detail=str(exc)) from excWithout the middleware, a tool returns the same result itself: return to_tool_error(ServiceError(...)).
add_error_contract covers two kinds of raised error and leaves every other exception alone, because an unclassified failure is a bug to see:
| A tool raises | The caller receives |
|---|---|
a ServiceError (including [db]’s AuthError) |
to_tool_error(err) |
a capacity refusal ([db]’s Overloaded) |
rate_limited_tool_error(err) |
| anything else | FastMCP’s own handling, unchanged |
It covers tool calls. A resource read has no in-band error result to return.
FastMCP logs every exception a tool raises at error level, with a traceback. add_error_contract drops that record for the errors it converts in tool calls on that server, so a caller’s mistake does not look like a server fault in the logs. The service_error line described below is the record to alert on. FastMCP’s record is kept for a resource read, a prompt, and a server without the contract.
What the caller receives
Section titled “What the caller receives”{ "isError": true, "content": [{ "type": "text", "text": "`query` is empty." }], "structuredContent": { "error": { "code": "bad_input", "retryable": false, "message": "`query` is empty." } }}upstream_status is added when the error came from from_upstream.
The codes
Section titled “The codes”ErrorCode is a closed set. Each code fixes the HTTP status a host presents and whether a retry can help.
| Code | HTTP status | Retryable | Use for |
|---|---|---|---|
bad_input |
400 | no | The caller’s arguments are wrong |
auth_required |
401 | no | No verified identity, or an upstream needs authorization |
forbidden |
403 | no | The operation is not permitted |
not_found |
404 | no | The record does not exist |
conflict |
409 | no | The request conflicts with the current state |
quota_exhausted |
502 | no | An upstream’s quota or credits ran out |
rate_limited |
429 | yes | The server or an upstream is at capacity |
upstream_rejected |
502 | no | An upstream refused the request |
upstream_unavailable |
503 | yes | An upstream is down |
upstream_timeout |
504 | yes | An upstream did not answer in time |
internal |
500 | no | A fault in the server |
message and detail
Section titled “message and detail”messagereaches the host and the model. Keep it generic and actionable. Omit it for the code’s default. Never put a vendor’s name, a URL, a raw response body, a secret or tenant data in it.detailis logged and never sent. The raw upstream text goes there.
Classifying an upstream
Section titled “Classifying an upstream”ServiceError.from_upstream(status) classifies an upstream HTTP status and passes the bare number to the host as upstream_status:
| Upstream status | Code |
|---|---|
| 401, 403, 404, 409 | auth_required, forbidden, not_found, conflict |
| 402 | quota_exhausted |
| 429 | rate_limited |
| 408, 504 | upstream_timeout |
| other 5xx | upstream_unavailable |
| other 4xx | upstream_rejected |
Every surfaced error is recorded once
Section titled “Every surfaced error is recorded once”- With
[observability]installed: one increment ofservice_errors_total{service, code, upstream_status}and oneservice_errorJSON log line carryingcode,retryable,upstream_status,http_statusanddetail. - Without it: the result is the same, nothing is counted, and the
service_errorline goes to the standard library loggernimblebrain_server_sdk.errorswith the same fields. bad_inputis logged atWARNING, since it is the caller’s mistake and the server worked. Every other code is logged atERROR.
A domain-specific error subclasses ServiceError and overrides metric_code to roll up to one of the codes above, so the metric’s label set stays closed.
Other errors the SDK raises
Section titled “Other errors the SDK raises”| Error | When |
|---|---|
ValueError, TypeError |
A bad argument at registration or call time: a facet level that does not exist, a record id prefix with a capital, a skill with no SKILL.md |
HostCapabilityMissing |
A host-resources call on a connection that cannot carry it |
MissingExtraError (an ImportError) |
A subpackage imported without its extra; the message names the extra |
AuthError, Overloaded, PoolConfigError, UnsafeRoleError |
From [db]; see Data |