Exceptions¶

All exceptions inherit from TarashException. Every exception exposes: message, provider, model, request_id, raw_response.

Retryability¶

The orchestrator uses this table to decide whether to try the next fallback:

Exception	Retryable	Typical cause
`GenerationFailedError`	✅	Provider failed, timeout, cancellation
`TimeoutError`	✅	Polling timed out (exposes `timeout_seconds`)
`HTTPConnectionError`	✅	Network failure
`HTTPError` (429, 500–504)	✅	Rate limit or server error (exposes `status_code`)
`ValidationError`	❌	Invalid request parameters
`ContentModerationError`	❌	Prompt violates content policy
`HTTPError` (400, 401, 403, 404)	❌	Bad request or auth error

Non-retryable errors are raised immediately regardless of fallback configuration.

Catching errors¶

from tarash.tarash_gateway.exceptions import (
    TarashException,
    ValidationError,
    ContentModerationError,
    GenerationFailedError,
    TimeoutError,
    HTTPConnectionError,
    HTTPError,
)

try:
    response = generate_video(config, request)
except ContentModerationError as e:
    print(f"Content moderation: {e.message}")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except TimeoutError as e:
    print(f"Timed out after {e.timeout_seconds}s, provider={e.provider}")
except HTTPConnectionError as e:
    print(f"Network failure: {e.message}, provider={e.provider}")
except GenerationFailedError as e:
    print(f"Generation failed: {e.message}, provider={e.provider}")
except TarashException as e:
    print(f"Other error: {e.message}")

Utilities¶

is_retryable_error(error) — returns True for errors that trigger fallback. Used internally by the orchestrator; useful when building custom retry logic.

handle_video_generation_errors — decorator applied to provider generate_video / generate_video_async methods. Lets TarashException and Pydantic ValidationError propagate unchanged; wraps any other exception in TarashException with full traceback in raw_response. See the Custom Providers guide.

TarashException ¶

TarashException(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: AnyDict | None = None,
)

Bases: Exception

Base class for all exceptions raised by the Tarash SDK.

Carries structured context (provider, model, request ID, raw provider response) to make debugging straightforward. Catch this class to handle any SDK error, or catch subclasses for more granular handling.

Attributes:

Name	Type	Description
`message`	`str`	Human-readable error description.
`provider`	`str \| None`	Provider identifier (e.g. `"fal"`, `"runway"`).
`model`	`str \| None`	Model name at the time of the error.
`request_id`	`str \| None`	Provider-assigned or Tarash-assigned request ID.
`raw_response`	`AnyDict \| None`	Unmodified provider response payload, if available.

Initialise a TarashException with structured context.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the error.	required
`provider`	`str \| None`	Provider identifier (e.g. `"fal"`).	`None`
`model`	`str \| None`	Model name used when the error occurred.	`None`
`request_id`	`str \| None`	Provider or Tarash request ID for tracing.	`None`
`raw_response`	`AnyDict \| None`	Raw provider response payload for debugging.	`None`

ValidationError ¶

ValidationError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: AnyDict | None = None,
)

Bases: TarashException

Raised when request parameters fail validation before or during generation.

Typically corresponds to a 400-level response from the provider. This error is not retryable — the same request will fail on every provider.

ContentModerationError ¶

ContentModerationError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: AnyDict | None = None,
)

Bases: TarashException

Raised when the prompt or input violates a provider's content policy.

Typically corresponds to a 403 response. This error is not retryable.

HTTPError ¶

HTTPError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: dict[str, object] | None = None,
    status_code: int | None = None,
)

Bases: TarashException

Raised on an unexpected HTTP error response from the provider API.

Retryable for server-side codes (429, 500, 502, 503, 504). Not retryable for client-side codes (400, 401, 403, 404).

Attributes:

Name	Type	Description
`status_code`	`int \| None`	HTTP status code returned by the provider, if available.

Initialise an HTTPError with an optional status code.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the HTTP error.	required
`provider`	`str \| None`	Provider identifier.	`None`
`model`	`str \| None`	Model name used when the error occurred.	`None`
`request_id`	`str \| None`	Request ID for tracing.	`None`
`raw_response`	`dict[str, object] \| None`	Raw provider response payload.	`None`
`status_code`	`int \| None`	HTTP status code (e.g. 429, 500).	`None`

GenerationFailedError ¶

GenerationFailedError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: AnyDict | None = None,
)

Bases: TarashException

Raised when the provider reports that generation failed.

Covers provider-side failures including internal errors, content timeouts within the provider's pipeline, and explicit cancellations. This error is retryable — a fallback provider may succeed.

HTTPConnectionError ¶

HTTPConnectionError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: AnyDict | None = None,
)

Bases: TarashException

Raised on a network-level failure before the provider responds.

Covers DNS resolution failures, connection refused, and other transport errors. This error is retryable — a fallback provider may be reachable.

TimeoutError ¶

TimeoutError(
    message: str,
    provider: str | None = None,
    model: str | None = None,
    request_id: str | None = None,
    raw_response: dict[str, object] | None = None,
    timeout_seconds: float | None = None,
)

Bases: TarashException

Raised when a request exceeds the configured timeout seconds.

This error is retryable — a fallback provider may respond faster.

Attributes:

Name	Type	Description
`timeout_seconds`	`float \| None`	The timeout value that was exceeded, in seconds.

Initialise a TimeoutError with the timeout duration.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description.	required
`provider`	`str \| None`	Provider identifier.	`None`
`model`	`str \| None`	Model name used when the timeout occurred.	`None`
`request_id`	`str \| None`	Request ID for tracing.	`None`
`raw_response`	`dict[str, object] \| None`	Raw provider response payload, if any.	`None`
`timeout_seconds`	`float \| None`	The timeout threshold that was exceeded.	`None`

is_retryable_error ¶

is_retryable_error(error: Exception) -> bool

Determine if an error should trigger a fallback retry.

Retryable errors (should try fallback): - GenerationFailedError: Video generation failed on provider side - TimeoutError: Request timed out - HTTPConnectionError: Network/connection failure - HTTPError with codes: 429 (rate limit), 500, 502, 503, 504 (server errors)

Non-retryable errors (should NOT try fallback): - ValidationError: Input validation failed (client error) - ContentModerationError: Content policy violation - HTTPError with codes: 400, 401, 403, 404 (client errors) - Other unknown exceptions

Parameters:

Name	Type	Description	Default
`error`	`Exception`	The exception to classify.	required

Returns:

Type	Description
`bool`	`True` if a fallback should be attempted, `False` otherwise.

handle_video_generation_errors ¶

handle_video_generation_errors(func: F) -> F

Decorator that wraps unhandled exceptions in TarashException.

Apply to provider generate_video and generate_video_async methods. Works with both sync and async functions automatically.

Behaviour: - [TarashException][] subclasses — propagate unchanged. - PydanticValidationError — propagate unchanged. - Any other exception — wrapped in [TarashException][] with full traceback captured in raw_response and logged at ERROR level.

Example

class MyProvider:
    @handle_video_generation_errors
    async def generate_video_async(self, config, request, on_progress=None):
        ...

    @handle_video_generation_errors
    def generate_video(self, config, request, on_progress=None):
        ...

handle_audio_generation_errors ¶

handle_audio_generation_errors(func: AF) -> AF

Decorator that wraps unhandled exceptions in TarashException.

Apply to provider generate_tts/generate_sts and their async variants. Works with both sync and async functions automatically.

Behaviour: - [TarashException][] subclasses — propagate unchanged. - PydanticValidationError — propagate unchanged. - Any other exception — wrapped in [TarashException][] with full traceback captured in raw_response and logged at ERROR level.