Skip to content

Implement uniform exceptions classes across model providers #1823

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
plpxsk wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Implement uniform exceptions classes across model providers #1823

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
e081ecb
Implement uniform exceptions classes across providers
plpxsk Mar 4, 2026
f0f7be4
Guard provider exception handlers against non-SDK errors
plpxsk Mar 12, 2026
0d51124
Remove unused APIError imports
plpxsk Mar 12, 2026
bf6ef20
Remove bad dependency
plpxsk Mar 12, 2026
baa24b7
Let local runtimes propagate native errors
plpxsk Mar 12, 2026
a1caa9e
Add comments that local runtimes bypass exceptions normalization
plpxsk Mar 13, 2026
6c1dcb6
Implement exceptions for chunk streams also
plpxsk Mar 13, 2026
2bb60de
Update docs
plpxsk Mar 18, 2026
4f915bf
Consolidate tests
plpxsk Mar 18, 2026
e9ac356
Use new BadRequestError for schema error
plpxsk Mar 19, 2026
aba41f0
Use new GenerationError for refusals
plpxsk Mar 19, 2026
159880c
Improve docs
plpxsk Mar 19, 2026
f5deb34
Reconcile tests
plpxsk Mar 19, 2026
3de42f0
Fix: add LM Studio to local models list
plpxsk Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Improve docs
  • Loading branch information
@plpxsk @RobinPicard
plpxsk authored and RobinPicard committed Mar 26, 2026
commit 159880c8283f3b132bbf55367aa34c2c798b15b4
22 changes: 8 additions & 14 deletions docs/features/core/exceptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,15 @@ title: Error Handling

# Error Handling

Native runtime exceptions are preserved for the following in-process local
runtimes:
For server-based models, Outlines provides a common exception hierarchy under `OutlinesError`.

* `LlamaCpp`
* `MLXLM`
* `transformers`
* `LMStudio`
For local models, native runtime exceptions are preserved (see list of local and server-based models at [Model Types](../models/index.md#model-types)).

But for the remaining **API-backed integrations** (Mistral, OpenAI, Ollama,
etc), Outlines provides a common exception hierarchy under `OutlinesError`, as
follows.
Exceptions normalization covers both sync and async modes, and both `generate` and `generate_stream()` (or equivalent) methods.

## Exception hierarchy
## Exception Hierarchy

All classes live in `outlines.exceptions`.
The common exception classes live in `outlines.exceptions`.

```
OutlinesError
Expand All @@ -35,7 +29,7 @@ OutlinesError
└── GenerationError
```

## Reference
## Quick Reference

| Class | Category | HTTP status(es) | Suggested user action |
| ----------------------- | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -77,7 +71,7 @@ except APIError as e:
raise
```

## `retryable` flag
## `retryable` Flag

Four exception types set `retryable = True`: `RateLimitError`, `ServerError`, `APITimeoutError`, and `APIConnectionError`. You can branch on this attribute without hardcoding a list of types:

Expand All @@ -90,7 +84,7 @@ except APIError as e:
raise
```

## Available attributes
## Available Attributes

Every `APIError` instance exposes:

Expand Down