> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.server.exception_handlers

## Module Contents

### Functions

| Name                                                                                                                         | Description                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [`_client_error_details`](#nemoguardrails-server-exception_handlers-_client_error_details)                                   | Extract the client-facing message and the OpenAI error fields from an exception.  |
| [`_error_response`](#nemoguardrails-server-exception_handlers-_error_response)                                               | Render the shared OpenAI error envelope as a JSON HTTP response.                  |
| [`_upstream_status`](#nemoguardrails-server-exception_handlers-_upstream_status)                                             | Read the upstream HTTP status off an exception, wherever that exception keeps it. |
| [`bad_request_error_handler`](#nemoguardrails-server-exception_handlers-bad_request_error_handler)                           | Return 400 for request/config combinations the caller can correct.                |
| [`http_exception_handler`](#nemoguardrails-server-exception_handlers-http_exception_handler)                                 | Render HTTPException (404, 422 guards, upstream 502, etc.) as the error envelope. |
| [`internal_error_handler`](#nemoguardrails-server-exception_handlers-internal_error_handler)                                 | Catch-all for unexpected errors.                                                  |
| [`invalid_state_error_handler`](#nemoguardrails-server-exception_handlers-invalid_state_error_handler)                       | -                                                                                 |
| [`llm_call_exception_handler`](#nemoguardrails-server-exception_handlers-llm_call_exception_handler)                         | Map LLM and engine call failures to their upstream HTTP status.                   |
| [`model_initialization_error_handler`](#nemoguardrails-server-exception_handlers-model_initialization_error_handler)         | Return 400 when a model fails to initialize from the configuration.               |
| [`rail_type_not_configured_error_handler`](#nemoguardrails-server-exception_handlers-rail_type_not_configured_error_handler) | -                                                                                 |
| [`validation_error_handler`](#nemoguardrails-server-exception_handlers-validation_error_handler)                             | Return 422 for request body validation failures.                                  |

### Data

[`log`](#nemoguardrails-server-exception_handlers-log)

### API

```python
nemoguardrails.server.exception_handlers._client_error_details(
    exc: BaseException
) -> tuple[str, typing.Union[str, int, None], typing.Optional[str], typing.Dict[str, str]]
```

Extract the client-facing message and the OpenAI error fields from an exception.

`code` and `param` come from the provider when it supplied them, and a
rate limit forwards its `Retry-After` so SDK backoff is not blind.

```python
nemoguardrails.server.exception_handlers._error_response(
    status_code: int,
    message: str,
    error_type: typing.Optional[str] = None,
    code: typing.Union[str, int, None] = None,
    param: typing.Optional[str] = None,
    headers: typing.Optional[typing.Dict[str, str]] = None
) -> starlette.responses.JSONResponse
```

Render the shared OpenAI error envelope as a JSON HTTP response.

```python
nemoguardrails.server.exception_handlers._upstream_status(
    exc: BaseException
) -> typing.Optional[int]
```

Read the upstream HTTP status off an exception, wherever that exception keeps it.

```python
nemoguardrails.server.exception_handlers.bad_request_error_handler(
    request: fastapi.Request,
    exc: nemoguardrails.exceptions.StreamingNotSupportedError
) -> starlette.responses.Response
```

async

Return 400 for request/config combinations the caller can correct.

These carry an actionable message (for example "enable streaming output
rails"), so they must not fall through to the 500 catch-all, which would
both hide the message and invite an SDK retry.

```python
nemoguardrails.server.exception_handlers.http_exception_handler(
    request: fastapi.Request,
    exc: starlette.exceptions.HTTPException
) -> starlette.responses.Response
```

async

Render HTTPException (404, 422 guards, upstream 502, etc.) as the error envelope.

`exc.headers` is forwarded because HTTP requires some of them (`Allow`
on 405, `WWW-Authenticate` on 401), and statuses that disallow a body get
an empty response rather than an envelope.

```python
nemoguardrails.server.exception_handlers.internal_error_handler(
    request: fastapi.Request,
    exc: Exception
) -> starlette.responses.Response
```

async

Catch-all for unexpected errors.

```python
nemoguardrails.server.exception_handlers.invalid_state_error_handler(
    request: fastapi.Request,
    exc: nemoguardrails.exceptions.InvalidStateError
) -> starlette.responses.Response
```

async

```python
nemoguardrails.server.exception_handlers.llm_call_exception_handler(
    request: fastapi.Request,
    exc: typing.Union[nemoguardrails.exceptions.LLMCallException, nemoguardrails.guardrails.model_engine.ModelEngineError, nemoguardrails.http.errors.HTTPClientError]
) -> starlette.responses.Response
```

async

Map LLM and engine call failures to their upstream HTTP status.

```python
nemoguardrails.server.exception_handlers.model_initialization_error_handler(
    request: fastapi.Request,
    exc: nemoguardrails.llm.models.initializer.ModelInitializationError
) -> starlette.responses.Response
```

async

Return 400 when a model fails to initialize from the configuration.

```python
nemoguardrails.server.exception_handlers.rail_type_not_configured_error_handler(
    request: fastapi.Request,
    exc: nemoguardrails.exceptions.RailTypeNotConfiguredError
) -> starlette.responses.Response
```

async

```python
nemoguardrails.server.exception_handlers.validation_error_handler(
    request: fastapi.Request,
    exc: fastapi.exceptions.RequestValidationError
) -> starlette.responses.Response
```

async

Return 422 for request body validation failures.

Only the field locations and messages are reported. `str(exc)` is the repr
of pydantic's error list, which embeds the raw request body (prompts,
tokens, PII), so it must reach neither the client nor the server log.

```python
nemoguardrails.server.exception_handlers.log = logging.getLogger(__name__)
```