---
title: Error Handling
---

# Error Handling

For server-based models, Outlines provides a common exception hierarchy under `OutlinesError`.

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

Exception normalization covers both sync and async modes, and both `generate` and `generate_stream()` (or equivalent) methods.

## Exception Hierarchy

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

```
OutlinesError
└── APIError
    ├── AuthenticationError
    ├── PermissionDeniedError
    ├── NotFoundError
    ├── RateLimitError
    ├── BadRequestError
    ├── ServerError
    ├── APITimeoutError
    ├── APIConnectionError
    ├── ProviderResponseError
    └── GenerationError
```

## Quick Reference

| Class                   | Category            | HTTP status(es)               | Suggested user action                                                                       |
| ----------------------- | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
| `AuthenticationError`   | Client error        | 401                           | Fix input: Check API key.                                                                    |
| `PermissionDeniedError` | Client error        | 403                           | Fix input: Check permissions for API key.                                                    |
| `NotFoundError`         | Client error        | 404                           | Fix input: Confirm model name, endpoint, etc.                                                |
| `RateLimitError`        | Client error        | 429                           | Retry: Slow down and retry, or reduce request frequency, batch size, etc.                   |
| `BadRequestError`       | Client error        | 400, 409, 413, 422, other 4xx | Fix input: Check prompt length, schema, unsupported parameters, etc.                        |
| `ServerError`           | Server error        | 5xx, 529 (Anthropic overload) | Retry: Perhaps retry after a short wait.                                                     |
| `APITimeoutError`       | Network/transport   | — (no HTTP status)            | Retry: Provider may be overloaded.                                                           |
| `APIConnectionError`    | Network/transport   | — (no HTTP status)            | Retry: Could not reach provider, check connection.                                           |
| `ProviderResponseError` | Response/generation | — (no HTTP status)            | Provider bug: May be a temporary issue or schema/format mismatch.                           |
| `GenerationError`       | Response/generation | — (no HTTP status)            | Inspect output: Output was refused, hit a content filter, reached the model's max-token limit, or similar. |

## Usage

Normalized `APIError` subclasses are raised by Outlines model wrappers. If you call a provider SDK directly, expect provider-native exceptions instead.

```python
from outlines.exceptions import (
    APIError,
    AuthenticationError,
    RateLimitError,
    ServerError,
    APITimeoutError,
    APIConnectionError,
)

try:
    result = model("Hello")
except AuthenticationError:
    print("Check your API key")
except RateLimitError as e:
    print(f"Rate limited by {e.provider}, back off and retry")
except APIError as e:
    if e.retryable:
        print(f"Transient error from {e.provider} (status={e.status_code}), retry")
    else:
        raise
```

## `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:

```python
except APIError as e:
    if e.retryable:
        time.sleep(backoff)
        retry()
    else:
        raise
```

## Available Attributes

Every `APIError` instance exposes:

| Attribute            | Type            | Description                                   |
| -------------------- | --------------- | --------------------------------------------- |
| `provider`           | `str \| None`   | Provider name, e.g. `"mistral"`, `"openai"` |
| `original_exception` | `Exception \| None` | The raw SDK exception                     |
| `status_code`        | `int \| None`   | HTTP status code, if available                |
| `request_id`         | `str \| None`   | Provider request ID, if available             |
| `retryable`          | `bool`          | Whether the error is worth retrying           |
| `hint`               | `str`           | Actionable suggestion shown in tracebacks                                 |
