Skip to main content

Venice AI SDK Exception Hierarchy

Exception Hierarchy:

VeniceError (base)
├── APIError (API-related errors)
│   ├── APIStatusError (HTTP status errors)
│   ├── AuthenticationError (401 Unauthorized)
│   ├── PermissionDeniedError (403 Forbidden)
│   ├── InvalidRequestError (400 Bad Request)
│   ├── NotFoundError (404 Not Found)
│   ├── ModelGoneError (410 Gone — retired/unroutable model)
│   ├── ConflictError (409 Conflict)
│   ├── UnprocessableEntityError (422 Unprocessable Entity)
│   ├── RateLimitError (429 Too Many Requests)
│   ├── PaymentRequiredError (402 Payment Required)
│   ├── InternalServerError (500+ Server Errors)
│   └── ServiceUnavailableError (503 Service Unavailable)
├── APIConnectionError (Network connectivity)
├── APITimeoutError (Request timeouts)
│   └── BillingTimeoutError (Billing API timeouts)
├── APIResponseProcessingError (Response parsing)
│   └── APIResponseValidationError (Pydantic validation)
├── StreamConsumedError (Stream already consumed)
├── StreamClosedError (Stream closed)
└── MissingStreamClassError (Configuration errors)

Example:

from venice_ai.exceptions import RateLimitError, AuthenticationError, APIError

try:
response = await client.chat.completions.create(...)
except RateLimitError as e:
print(f"Rate limited, retry after {e.retry_after_seconds}s")
except AuthenticationError:
print("Check your API key")
except APIError as e:
print(f"API error: {e.status_code} - {e}")

VeniceAPIErrorCode Objects​

class VeniceAPIErrorCode(StrEnum)

Machine-readable error codes the Venice API may return.

The Venice error envelope is not uniform: many endpoints return a bare string message ({"error": "Model is required"}), validation failures return a Zod-style shape ({"details": {...}, "issues": [...]}), and the schema'd errors carry a machine-readable code as a top-level field (response["code"]) — not nested under error. This enum models those top-level codes; exc.code is None when the error carried only a string message.

The enum tracks the official Venice error-codes table but is not guaranteed exhaustive — the API may return new codes before this enum (or the public docs) is updated, so callers should treat an unrecognized exc.code string defensively rather than assuming enum membership.

Using this enum enables type-safe matching instead of comparing raw strings:

from venice_ai.exceptions import RateLimitError, VeniceAPIErrorCode

try:
    response = await client.chat.completions.create(...)
except RateLimitError as exc:
    if exc.code == VeniceAPIErrorCode.RATE_LIMIT_EXCEEDED:
        ...

VeniceError Objects​

class VeniceError(Exception)

Base exception for all errors raised by the Venice AI SDK.

Attributes:

  • message - Human-readable description of what went wrong.
  • request_obj - The request object that caused the error, if available.
  • response_obj - The HTTP response object, if available.

APIError Objects​

class APIError(VeniceError)

Base exception for all API-related errors from the Venice AI service.

Raised when the API returns a non-success HTTP status code.

Attributes:

  • status_code - HTTP status code from the API response.
  • body - Parsed response body containing error details, if available.
  • code - Venice API error code string, if present in the response body.

APIStatusError Objects​

class APIStatusError(APIError)

Raised when the API returns a non-success status code.

Initialised with the response object and parsed body for detailed error information.

AuthenticationError Objects​

class AuthenticationError(APIError)

Raised for 401 Unauthorized errors — invalid or missing API key.

PermissionDeniedError Objects​

class PermissionDeniedError(APIError)

Raised for 403 Forbidden errors — authenticated but not authorised.

InvalidRequestError Objects​

class InvalidRequestError(APIError)

Raised for 400 Bad Request errors, and also 413/415 status codes.

Common causes: missing required fields, invalid parameter values, oversized files, or unsupported content types.

NotFoundError Objects​

class NotFoundError(APIError)

Raised for 404 Not Found errors — resource or endpoint not found.

ModelGoneError Objects​

class ModelGoneError(APIError)

Raised for HTTP 410 Gone — the requested model has been retired and could not be auto-routed to a replacement.

Venice auto-routes deprecated models to a similar model where possible; a 410 means routing was not possible (technical or safety reasons). Pick a current model (see client.models.list()) or resolve one via traits.

ConflictError Objects​

class ConflictError(APIError)

Raised for 409 Conflict errors — resource conflict or concurrent modification.

UnprocessableEntityError Objects​

class UnprocessableEntityError(APIError)

Raised for 422 Unprocessable Entity errors — server-side validation failures.

RateLimitError Objects​

class RateLimitError(APIError)

Raised for 429 Too Many Requests errors when rate limits are exceeded.

Attributes:

  • retry_after_seconds - Seconds to wait before retrying, parsed from the Retry-After header (may be None).
  • remaining_requests - Requests remaining in the current window, if reported.
  • reset_requests_timestamp - Absolute Unix timestamp in seconds when the request limit resets, normalized from the millisecond-epoch x-ratelimit-reset-requests header.
  • cached_rate_limit_headers - Pre-extracted rate-limit headers (lowercase keys) for use by distributed backend state synchronisation.

PaymentRequiredError Objects​

class PaymentRequiredError(APIError)

Raised for 402 Payment Required errors — insufficient balance or credits.

InternalServerError Objects​

class InternalServerError(APIError)

Raised for all 5xx server-side errors except 503.

Dispatch is by HTTP status range, not by API error code: any status in 500-599 maps here except 503, which has its own subclass (:class:ServiceUnavailableError). Known HTTP 500 error codes include INFERENCE_FAILED, UPSCALE_FAILED, and UNKNOWN_ERROR; other 5xx statuses (e.g. 502, 504) fall through to this class as well.

ServiceUnavailableError Objects​

class ServiceUnavailableError(APIError)

Raised for 503 Service Unavailable errors — service temporarily down.

Clients should implement retry logic with exponential backoff when encountering this error.

APIConnectionError Objects​

class APIConnectionError(VeniceError)

Raised when there is a network-level connectivity issue.

Covers DNS failures, TCP connection errors, SSL/TLS problems, and proxy configuration issues.

Attributes:

  • original_error - The underlying exception that triggered this error.

APITimeoutError Objects​

class APITimeoutError(VeniceError)

Raised when an API request exceeds the configured timeout.

Attributes:

  • original_error - The underlying timeout exception.

BillingTimeoutError Objects​

class BillingTimeoutError(APITimeoutError)

Raised when a billing API request times out.

The Venice AI billing API is known to hang on very small date ranges (< ~15 minutes) or queries that return no results. The SDK uses an aggressive 10-second timeout to fail fast on these queries.

Common causes:

  • Date range smaller than ~15 minutes
  • Query returns no data (empty result set)
  • Complex filters on sparse data

Tip: use a date range of at least one full day where data is known to exist.

APIResponseProcessingError Objects​

class APIResponseProcessingError(VeniceError)

Raised when the client fails to process a received API response.

Covers JSON parse errors, unexpected response structure, missing fields, and type conversion failures.

Attributes:

  • original_error - The underlying parse / processing exception.

APIResponseValidationError Objects​

class APIResponseValidationError(APIResponseProcessingError)

Raised when Pydantic validation fails on an API response.

Indicates a mismatch between the expected response schema and the actual response — typically caused by an API format change.

Attributes:

  • validation_error - The original pydantic.ValidationError.
  • response_data - The raw response data that failed validation.
  • model_name - The Pydantic model name that failed validation.

VideoGenerationError Objects​

class VideoGenerationError(VeniceError)

Raised when a video generation job fails on the server.

Attributes:

  • error_code - The error code returned by the API, if available.

MusicGenerationError Objects​

class MusicGenerationError(VeniceError)

Raised when a music generation job fails on the server.

Attributes:

  • error_code - The error code returned by the API, if available.

MissingStreamClassError Objects​

class MissingStreamClassError(VeniceError)

Raised when stream=True is passed but no stream_cls is provided.

StreamConsumedError Objects​

class StreamConsumedError(VeniceError)

Stream has already been consumed and cannot be read again.

StreamClosedError Objects​

class StreamClosedError(VeniceError)

Stream has been closed and cannot be read.

TeeError Objects​

class TeeError(VeniceError)

Base exception for Venice TEE (Trusted Execution Environment) / E2EE errors.

Raised for failures in the confidential-compute end-to-end-encryption path (venice_ai.tee): attestation verification, key agreement, and encrypt/decrypt of message content. Subclasses :class:VeniceError.

TeeAttestationError Objects​

class TeeAttestationError(TeeError)

Raised when TEE attestation verification fails (fail-closed).

Examples: the server reported verified == false; the response nonce did not match the client-sent nonce; the report-data binding did not match the expected signing_address || zero-pad || nonce layout; or TDX debug flags were set. The SDK fails closed — it raises rather than proceeding with an unverified enclave.

TeeEncryptionError Objects​

class TeeEncryptionError(TeeError)

Raised when TEE end-to-end encryption or decryption fails.

Examples: a message could not be encrypted to the model key, or an encrypted response chunk could not be decrypted / authenticated (GCM tag mismatch).

MaxIterationsExceededError Objects​

class MaxIterationsExceededError(VeniceError)

Raised when chat.completions.run_with_tools doesn't converge.

The tool-orchestration loop runs at most max_iterations model round trips before giving up. If every iteration ends with finish_reason="tool_calls", the loop is either looping pathologically (model keeps requesting tools that don't satisfy it) or the cap was set too low.

Attributes:

  • iterations - How many round trips were attempted (== max_iterations).
  • messages - The full message history at the time of failure, including every assistant tool-call turn and tool-result the loop produced. Useful for diagnosing why the loop didn't converge.
  • last_response - The model's last (still-tool-calling) response, in case it carries diagnostic clues — e.g. usage information or unusual tool-call shapes.