nemoguardrails.server.exception_handlers | NVIDIA NeMo Guardrails Library Developer Guide

Module Contents

Functions

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

Data

NONSTREAMING_RETRY_AFTER_SECONDS

STREAMING_RETRY_AFTER_SECONDS

log

API

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.

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.

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

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

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.

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.

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

async

Catch-all for unexpected errors.

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

async

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.

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.

nemoguardrails.server.exception_handlers.queue_full_error_handler(
    request: fastapi.Request,
    exc: asyncio.QueueFull
) -> starlette.responses.Response

async

Render IORails admission shedding as a retryable overload response.

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

async

nemoguardrails.server.exception_handlers.streaming_capacity_error_handler(
    request: fastapi.Request,
    exc: nemoguardrails.exceptions.StreamingCapacityExceededError
) -> starlette.responses.Response

async

Render IORails streaming capacity shedding as a retryable overload response.

A full streaming semaphore is a different condition from a full admission queue, so it gets its own message rather than reporting the queue.

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.

nemoguardrails.server.exception_handlers.NONSTREAMING_RETRY_AFTER_SECONDS = 30

nemoguardrails.server.exception_handlers.STREAMING_RETRY_AFTER_SECONDS = 30

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