5. Errors the model can use¶
A model reads an error and decides what to do next. "Exception: KeyError 'b-999'" tells it nothing. A good error says what went wrong, whether trying again helps, and what to do instead.
Raising errors¶
Raise one of OunceMCP's errors, with a message for the model and a hint:
raise NotFound(f"No book with id '{id}'.", hint="Use books.search to find ids.")
raise InvalidInput("The query is empty.", hint="Give at least one word from a title or author.")
raise PermissionDenied(f"All copies of '{book.title}' are on loan.",
hint="Tell the user; suggest another book by the same author.")
The model receives the text and a category in _meta:
{"ouncemcp": {"error": "not_found", "category": "not_found", "retryable": false,
"docs": "https://github.com/subbusainath/ouncemcp/blob/main/docs/errors/not_found.md"}}
The eight categories¶
| Raise | Category | Retryable | Use it when |
|---|---|---|---|
InvalidInput |
validation |
no | The arguments are wrong. Say which and how to fix them. |
AuthenticationRequired |
authentication |
no | The caller must sign in. |
PermissionDenied |
permission |
no | The caller may not do this, or the action is not allowed now. |
NotFound |
not_found |
no | The thing does not exist for this caller. |
RateLimited |
rate_limit |
yes | Too many calls. Pass retry_after= seconds. |
TransientError |
transient |
yes | An upstream failed in a way that may pass. |
AmbiguousWrite |
ambiguous_write |
no | A write may or may not have happened (chapter 6). |
| any other exception | internal |
no | A bug. The model sees only a reference id. |
Pydantic validation errors on arguments become validation automatically, with the field names.
Warning
Never put secrets or internal details in a message. Unexpected exceptions are already hidden: the model sees internal and a reference id, and the full traceback goes to your logs. Messages from OunceMCP errors are shown, after redaction of anything that looks like a token or key.
Not found, not forbidden¶
When a member of the south branch asks for a north book (chapter 7), Shelf answers not_found, not permission. Saying "forbidden" would tell an intruder the book exists. Use PermissionDenied when the caller already knows the thing exists, such as their own loan they may not extend.
Retries are automatic for reads¶
Transient failures of read tools are retried with bounded backoff, inside the deadline, before the model ever sees them. Writes are never retried: a write that fails halfway may already have happened. The next chapter is about exactly that.
Summary¶
- Raise a category error with a message and a hint that says what to do next.
- Unexpected exceptions never leak; the model sees a reference id.
- Prefer
not_foundtopermissionwhen existence itself is private. - Reads are retried for you; writes never are.
The error reference has a page for each category.