Skip to content

Errors

Stable

Covered by the 1.0 API freeze (proposal 0029): no breaking change before 2.0.

Raise these from a tool to give the model a category, a code and a hint. Each category has a page in the error reference.

OunceError

OunceError(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: Exception

Base for failures a tool author raises on purpose.

message is shown to the caller after redaction, so write it for the agent: say what went wrong and how to fix it, and leave out hosts, credentials and stack traces. hint is appended. retry_after (seconds) is meaningful for rate limits.

InvalidInput

InvalidInput(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

The arguments are wrong. Retrying the same call cannot help.

AuthenticationRequired

AuthenticationRequired(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

The caller has no valid credentials. Reauthorize through the permitted flow.

PermissionDenied

PermissionDenied(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

The caller is known and not allowed. Never suggest broader authority.

NotFound

NotFound(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

The thing asked for does not exist, or the caller cannot see it.

RateLimited

RateLimited(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

A limit was hit. Set retry_after (seconds) when the upstream says when.

TransientError

TransientError(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

A temporary failure. For reads, OunceMCP retries within the deadline.

AmbiguousWrite

AmbiguousWrite(message: str, *, hint: str | None = None, retry_after: float | None = None)

Bases: OunceError

A write may or may not have been applied. Callers must check state first.

InvalidCursor

InvalidCursor(reason: CursorProblem = 'malformed')

Bases: ValueError

Raised when a cursor cannot be used for this call.

reason says why: malformed, legacy, signature, expired, tool, principal or query. The message tells the agent how to recover.

ResultTooLarge

ResultTooLarge(min_tokens: int, budget: int, truncation: Truncation, items: int | None = None)

Bases: Exception

The smallest schema-valid result is still over the budget (spec RES-8).

Attributes:

Name Type Description
min_tokens

Size of the smallest valid result, including its note.

budget

The result budget for the call.

truncation

What shaping removed before giving up.

items

Items left in the largest list, or None when no list is left to trim. A lower limit can only help when this is above 1.

reason property

reason: str

item_over_budget, min_items_over_budget or fixed_over_budget.