Skip to main content
VectorAI DB uses standard gRPC status codes for all errors. The Python SDK maps these to typed exceptions so you can handle them precisely in your application code.
Error transportgRPC status codes
SDK exceptionsactian_vectorai.exceptions module
SDK versionAll versions

​
gRPC status codes

VectorAI DB returns the following gRPC status codes.
Status codeNumericMeaning
OK0Success
INVALID_ARGUMENT3Bad request — malformed input or wrong parameter type
NOT_FOUND5Collection or point does not exist
ALREADY_EXISTS6Collection with this name already exists
RESOURCE_EXHAUSTED8Server at capacity — too many connections or requests
FAILED_PRECONDITION9Operation not permitted in current state
ABORTED10Concurrent modification conflict
UNIMPLEMENTED12Operation not supported by this server edition
INTERNAL13Unexpected server-side error
UNAVAILABLE14Server not reachable or not yet ready
UNAUTHENTICATED16Missing or invalid API key

​
Python SDK exceptions

The Python SDK raises typed exceptions that wrap the underlying gRPC status codes. All exceptions inherit from VectorAIError, which you can use as a catch-all.
Exception classgRPC codeWhen raised
VectorAIInvalidArgumentErrorINVALID_ARGUMENTWrong input type or malformed request
VectorAINotFoundErrorNOT_FOUNDCollection or point does not exist
VectorAIAlreadyExistsErrorALREADY_EXISTSCreating a collection that already exists
VectorAIResourceExhaustedErrorRESOURCE_EXHAUSTEDServer capacity limit reached
VectorAIUnavailableErrorUNAVAILABLECannot connect to the server
VectorAIUnauthenticatedErrorUNAUTHENTICATEDInvalid or missing API key
VectorAIInternalErrorINTERNALUnexpected server error
VectorAIErrorAnyBase class for all SDK errors

​
Handle errors in application code

The following patterns show you how to catch and respond to specific exception types.

​
Catch specific exceptions

Use a try/except block to catch specific exceptions and handle each error type appropriately. 
from actian_vectorai import (
    VectorAIClient,
    VectorAIError,
    CollectionNotFoundError,
    UnimplementedError,
    VectorAITimeoutError,
    is_retryable,
    get_retry_delay,
)

with VectorAIClient("localhost:50051") as client:
    try:
        results = client.points.search("products", vector=query, limit=10)
    except CollectionNotFoundError as e:
        print(f"Collection '{e.collection_name}' not found")
    except UnimplementedError as e:
        print(f"Operation '{e.operation}' not supported by server")
    except VectorAITimeoutError:
        print("Request timed out — try increasing timeout")
    except VectorAIError as e:
        if is_retryable(e):
            delay = get_retry_delay(e, attempt=1)
            print(f"Transient error, retry after {delay:.1f}s")
        else:
            raise

​
Create a collection idempotently

Catch VectorAIAlreadyExistsError to skip creation when the collection already exists. 
from actian_vectorai.exceptions import VectorAIAlreadyExistsError

try:
    client.create_collection(
        name="product-embeddings",
        vectors_config={"size": 1536, "distance": "Cosine"},
    )
except VectorAIAlreadyExistsError:
    pass  # Collection already exists — safe to continue

​
Retry on transient errors

Use exponential backoff for UNAVAILABLE and RESOURCE_EXHAUSTED errors, which are often transient. 
import time
from actian_vectorai.exceptions import VectorAIUnavailableError, VectorAIResourceExhaustedError

RETRYABLE = (VectorAIUnavailableError, VectorAIResourceExhaustedError)

def search_with_retry(client, collection_name, query_vector, limit, max_retries=3):
    delay = 1.0
    for attempt in range(max_retries):
        try:
            return client.search(
                collection_name=collection_name,
                query_vector=query_vector,
                limit=limit,
            )
        except RETRYABLE as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(delay)
            delay *= 2

​
Inspect error details

Every SDK exception exposes the underlying gRPC status code and a human-readable message. Use these fields to log errors or build custom handling logic. 
from actian_vectorai.exceptions import VectorAIError

try:
    client.search(...)
except VectorAIError as e:
    print(f"Code:    {e.grpc_status_code}")
    print(f"Message: {e.message}")
    print(f"Details: {e.details}")

​
Common error messages

Expand each section for details about what causes each error and how to resolve it.
Code: NOT_FOUNDMessage: collection 'my-collection' does not existCause: The collection name is misspelled, or the collection was deleted.Fix: Call client.list_collections() to verify the collection exists before operating on it.
Code: INVALID_ARGUMENTMessage: vector size mismatch: expected 1536, got 768Cause: The query vector or inserted vector has a different number of dimensions than the collection’s configuration.Fix: Confirm the embedding model and collection dimensions match.
Code: UNAUTHENTICATEDMessage: invalid or missing API keyCause: The server has API key auth enabled but the client did not supply a key, or supplied the wrong key.Fix: Pass api_key to VectorAIClient.
client = VectorAIClient("localhost:50051", api_key="your-secret-key")
Code: INTERNALMessage: internal server errorCause: Unexpected condition on the server side, typically a bug or disk/memory exhaustion.Fix: Check server logs for details. If the error persists, then contact Actian support.

​
Next steps

Explore these related guides to learn more.

Troubleshooting

Diagnose connection, search, and startup issues.

Best practices

Recommended error handling patterns for production applications.

Python SDK

Full SDK reference including the exceptions module.

Configuration

Configure timeouts and connection limits to reduce transient errors.