Control APIs

Errors

HTTP status codes, error types, and structured error payloads returned by the MuBit control API.

Every error response carries a flat JSON body with a single human-readable error string:

{
  "error": "ingest request exceeds the 1000-item limit"
}

There is no nested type/code envelope and no request_id field on the response body. Map programmatically on the HTTP status code (below) or, over gRPC, on the canonical status code. The HTTP API is a thin shell over the gRPC service, so every HTTP status is derived from a gRPC code.

Status codes

Status	gRPC code	Meaning	Retryable?
`400`	`InvalidArgument`	Request shape rejected — missing/invalid field, or an input cap exceeded (e.g. >1000 items)	No
`401`	`Unauthenticated`	Missing or invalid `Authorization` header	No
`403`	`PermissionDenied`	Key is valid but not scoped to this run/session/resource	No
`404`	`NotFound`	Session, agent, reference id, or job id does not exist	No
`409`	`AlreadyExists`	A unique resource (project, agent, skill, …) already exists	No
`410`	—	Endpoint was removed (legacy core SDM lanes); use `insert`/`search` instead	No
`429`	`ResourceExhausted`	An upstream dependency (e.g. an LLM provider) is throttling	Yes (with backoff)
`500`	`Internal` (and unmapped)	Unhandled server error	Yes (with backoff)
`503`	`Unavailable` / `FailedPrecondition`	Backend temporarily unavailable or a precondition is not yet met	Yes (with backoff)

ℹ️Note

The runtime does not currently emit 422, 499, 502, or 504. Business-rule rejections surface as 400 (InvalidArgument); overload and unmet preconditions surface as 503. See Rate limits for what is and isn't throttled.

SDK exception mapping

The Python SDK raises typed exceptions exported from the top-level mubit package (there is no mubit.errors submodule):

Exception	Raised for
`mubit.AuthError`	`401` — bad, missing, or revoked key
`mubit.ValidationError`	`400` — wrong request shape or a rejected business rule
`mubit.AlreadyExistsError`	`409` — duplicate unique resource (subclass of `ValidationError`)
`mubit.UnsupportedFeatureError`	A call the current server/transport doesn't support
`mubit.ServerError`	`5xx` — server-side failure (retryable)
`mubit.TransportError`	Network/transport failure; carries a `.code` (e.g. `UNAVAILABLE`, `DEADLINE_EXCEEDED`)

import mubit
 
client = mubit.Client()
try:
    client.remember(session_id=run_id, agent_id="support-agent", content="…", intent="fact")
except mubit.AuthError:
    raise                         # fix the API key — don't retry
except mubit.ValidationError:
    raise                         # fix the call shape — don't retry
except (mubit.ServerError, mubit.TransportError):
    ...                           # transient — safe to retry (see below)

ServerError and transient TransportErrors are the retryable cases; auth, validation, and unsupported-feature errors are not. The SDK already retries the transient ones for you — see Retries and idempotency for the policy and the manual pattern.