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 ¶
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 ¶
AuthenticationRequired ¶
PermissionDenied ¶
NotFound ¶
RateLimited ¶
TransientError ¶
AmbiguousWrite ¶
InvalidCursor ¶
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 ¶
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 |