Error Handling

The Oracle VecDB Python SDK raises VecDBError subclasses for SDK-level configuration failures. Public API methods normalize resource-name validation, argument validation, and service failures as VecDBException.

Errors returned by the database or ORDS service are normalized as VecDBException and are also described on this page.

Catch SDK errors

from oracle_vecdb import (
    OracleVecDB,
    Configuration,
    InsecureConnectionError,
    InvalidHostFormatError,
    VecDBError,
    VecDBException,
)

try:
    client = OracleVecDB(
        Configuration(rest_url="http://<host>/ords/<schema>/_/db-api/stable/vecdb/")
    )
except InsecureConnectionError as error:
    print(error.get_error_cause_action())
except InvalidHostFormatError as error:
    print(error.get_error_cause_action())
except VecDBError as error:
    print(error.get_error())
except VecDBException as error:
    print(error)

Use get_error() for the message and underlying exception text. Use get_error_cause_action() when the cause and recommended action are also useful. print_error() and print_oerr() are available for diagnostic output.

`VecDBError`

Base class for named Oracle VecDB Python SDK configuration errors.

`VecDBException`

Base exception for normalized API validation, ORDS, and database service errors. Catch this class for public API method failures.

VecDBException exposes the HTTP status, normalized error_code and error_message, service-neutral cause and action guidance, and the wrapped original_exception. Use error.is_original_exception(InvalidTableNameFormatError) or inspect error.exception_type when an application needs to distinguish a validation error from a transport error. The aliases code, message, type, instance, diagnosticTrace, stackTrace, and traceback match service error response field names.

When an API page identifies an Invalid...Error, the public method surfaces a VecDBException whose original_exception retains that named validation error.

Use error.format(include_trace=True) when diagnostic and service traces are required. Use error.get_traceback() to retrieve the captured traceback without formatting the other details. These diagnostic values redact credentials, bearer tokens, cookies, API keys, and signed URL parameters.

API argument validation

Public API methods validate arguments before sending a request. Invalid resource names, types, values, and required list contents are surfaced as VecDBException.

Operation group	Validation
List operations	`limit` must be positive and `offset` must be non-negative.
`generate_embedding()`	`inputs` must be a non-empty list.
`rerank()`	`documents` must be a non-empty list of strings.
`list_vectors()` and `delete_vectors()`	`ids` must be a list of strings when provided.
`upsert_vectors()`	`vectors` must be a list of dictionaries or vector model objects.
Request objects	`annotations`, `params`, `query_by`, `filters`, `advanced_options`, and `model_params` must be dictionaries when provided.
Index operations	`index_params` accepts documented snake-case fields only.

`InsecureConnectionError`

Error code: VECDB-001

Raised when a configuration URL uses http://. Use HTTPS so authentication details are not sent in clear text.

Action: Change the configured URL to start with https://.

`InvalidHostFormatError`

Error code: VECDB-002

Raised when the configured REST URL does not match the required ORDS /vecdb/ URL structure.

Action: Use a URL such as https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/.

`InvalidTableNameFormatError`

Error code: VECDB-003

Raised when a vector table name does not match the required identifier format.

Action: Use only letters, digits, and underscores (_) in the table name.

Raised by: create_vector_table(), describe_vector_table(), drop_vector_table(), update_vector_table_annotation(), upsert_vectors(), list_vectors(), load_vectors(), delete_vectors(), query(), create_index(), describe_index(), rebuild_index(), and drop_index().

`InvalidModelNameFormatError`

Error code: VECDB-004

Raised when a model name does not match the required identifier format.

Action: Use only letters, digits, and underscores (_) in the model name.

Raised by: load_model(), describe_model(), drop_model(), and generate_embedding().

`InvalidLoadJobNameFormatError`

Error code: VECDB-005

Raised when a vector load job name does not match the required identifier format.

Action: Use only letters, digits, and underscores (_) in the load job name.

Raised by: describe_vector_load_job() and get_vector_load_job_log().

`InvalidIndexJobNameFormatError`

Error code: VECDB-006

Raised when an index job name does not match the required identifier format.

Action: Use only letters, digits, and underscores (_) in the index job name.

`VectorPayloadTooLargeError`

Error code: VECDB-007

Raised when a single vector record exceeds the largest payload the SDK can safely send during upsert_vectors() batching.

Action: Reduce the vector or metadata size, or use load_vectors() for bulk ingestion.

Raised by: upsert_vectors().

`InvalidVectorsError`

Error code: VECDB-008

Raised when upsert_vectors() receives None or an empty vector list.

Action: Pass a non-empty list of vector records.

Raised by: upsert_vectors().

`ResourceNotFoundError`

Error code: VECDB-009

Raised when a requested resource does not exist.

Action: Verify the resource name and try again.

Raised by: get_vector_load_job_log() and get_index_job_log().

`InvalidLoadJobLogError`

Error code: VECDB-010

Raised when a vector load job has not reached a terminal state.

Action: Wait until the load job is SUCCEEDED, FAILED, STOPPED, or BROKEN before requesting its log.

Raised by: get_vector_load_job_log().

`InvalidIndexJobLogError`

Error code: VECDB-011

Raised when an index job has not reached a terminal state.

Action: Wait until the index job is SUCCEEDED, FAILED, STOPPED, or BROKEN before requesting its log.

Raised by: get_index_job_log().

Raised by: describe_index_job() and get_index_job_log().