praval.core.exceptions

Custom exceptions for the Praval framework.

These exceptions provide clear error handling and debugging information for common issues in LLM agent operations.

Exceptions

ConfigurationError

Raised when there are configuration validation issues.

EmbeddingConfigurationError

Raised when persistent vectors do not match embedding configuration.

HITLConfigurationError

Raised when HITL policy requires approval for a HITL-disabled agent.

InterventionRequired(intervention_id, ...[, ...])

Raised when a tool call is paused waiting for human intervention.

PravalConfigurationError

Raised when typed application or lifecycle configuration is invalid.

PravalError

Base exception for all Praval-related errors.

ProviderAuthenticationError([message, ...])

The provider rejected the credentials or permissions (401/403).

ProviderError([message, provider, model, ...])

Raised when there are issues with LLM provider operations.

ProviderInvalidRequestError([message, ...])

The provider rejected the request itself (400/404/422).

ProviderInvalidResponseError([message, ...])

Raised when a final response fails local structured-output validation.

ProviderQuotaError([message, provider, ...])

The account's quota or credit is exhausted; retrying will not help.

ProviderRateLimitError([message, provider, ...])

The provider throttled the request (429); retry after a delay.

ProviderTransportError([message, provider, ...])

The request did not complete: connection failure or timeout.

ProviderUnavailableError([message, ...])

The provider failed or is overloaded (5xx, 529).

StateError

Raised when there are issues with state persistence operations.

ToolError

Raised when there are issues with tool registration or execution.

ToolRoundLimitError([message, limit, ...])

A tool loop exceeded its configured round limit; never retried.
exception praval.core.exceptions.PravalError[source]

Bases: Exception

Base exception for all Praval-related errors.

exception praval.core.exceptions.ProviderError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: PravalError

Raised when there are issues with LLM provider operations.

The message stays the exception’s string form, so ProviderError("...") keeps working. Keyword fields describe a failed provider request when the runtime or an adapter knows them. retryable defaults to the class policy: rate limits, unavailability and transport failures are retryable, everything else is not.

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

default_retryable = False
__init__(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]
Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

exception praval.core.exceptions.ProviderAuthenticationError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The provider rejected the credentials or permissions (401/403).

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

exception praval.core.exceptions.ProviderInvalidRequestError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The provider rejected the request itself (400/404/422).

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

exception praval.core.exceptions.ProviderQuotaError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The account’s quota or credit is exhausted; retrying will not help.

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

exception praval.core.exceptions.ProviderRateLimitError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The provider throttled the request (429); retry after a delay.

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

default_retryable = True
exception praval.core.exceptions.ProviderUnavailableError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The provider failed or is overloaded (5xx, 529).

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

default_retryable = True
exception praval.core.exceptions.ProviderTransportError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

The request did not complete: connection failure or timeout.

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None

default_retryable = True
exception praval.core.exceptions.ToolRoundLimitError(message='', *, limit=None, provider=None, model=None)[source]

Bases: ProviderError

A tool loop exceeded its configured round limit; never retried.

Parameters:

  • message (str)

  • limit (int | None)

  • provider (str | None)

  • model (str | None)

Return type:

None

__init__(message='', *, limit=None, provider=None, model=None)[source]
Parameters:

  • message (str)

  • limit (int | None)

  • provider (str | None)

  • model (str | None)

Return type:

None

exception praval.core.exceptions.ConfigurationError[source]

Bases: PravalError

Raised when there are configuration validation issues.

exception praval.core.exceptions.PravalConfigurationError[source]

Bases: ConfigurationError

Raised when typed application or lifecycle configuration is invalid.

exception praval.core.exceptions.EmbeddingConfigurationError[source]

Bases: ConfigurationError

Raised when persistent vectors do not match embedding configuration.

exception praval.core.exceptions.ToolError[source]

Bases: PravalError

Raised when there are issues with tool registration or execution.

exception praval.core.exceptions.StateError[source]

Bases: PravalError

Raised when there are issues with state persistence operations.

exception praval.core.exceptions.InterventionRequired(intervention_id, run_id, agent_name, tool_name, reason='')[source]

Bases: PravalError

Raised when a tool call is paused waiting for human intervention.

Parameters:

  • intervention_id (str)

  • run_id (str)

  • agent_name (str)

  • tool_name (str)

  • reason (str)

__init__(intervention_id, run_id, agent_name, tool_name, reason='')[source]
Parameters:

  • intervention_id (str)

  • run_id (str)

  • agent_name (str)

  • tool_name (str)

  • reason (str)

exception praval.core.exceptions.HITLConfigurationError[source]

Bases: PravalError

Raised when HITL policy requires approval for a HITL-disabled agent.

exception praval.core.exceptions.ProviderInvalidResponseError(message='', *, provider=None, model=None, operation=None, status_code=None, error_code=None, request_id=None, retryable=None, retry_after_seconds=None)[source]

Bases: ProviderError

Raised when a final response fails local structured-output validation.

Only raised when StructuredOutputConfig.validate_locally is true and the final content is not JSON or does not match the requested schema.

Parameters:

  • message (str)

  • provider (str | None)

  • model (str | None)

  • operation (str | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • retryable (bool | None)

  • retry_after_seconds (float | None)

Return type:

None