Errors

The SDK reports failures as named exceptions, never as HTTP status codes for you to interpret. Nothing from an underlying library escapes; every failure is translated into one of the SDK’s own exception types before it reaches you.

The exception tree

Every exception descends from ArangoAIError. The tree is deliberately shallow: a root, two families, and concrete errors underneath.

ArangoAIError
|-- AuthenticationError
|   |-- InvalidCredentialsError
|   `-- TokenRefreshError
`-- CommunicationError
    |-- PlatformUnreachableError
    `-- ServiceError
        |-- DatabaseNotFoundError
        |-- InvalidProjectNameError
        |-- ProjectNotFoundError
        |-- InvalidSecretNameError
        |-- InvalidSecretValueError
        |-- SecretProfileNotFoundError
        |-- InvalidFileScopeError
        |-- InvalidFileMetadataError
        |-- EmptyFileError
        |-- FileBatchTooLargeError
        |-- FileUploadFailedError
        |-- InvalidServiceParametersError
        |-- ServiceNotFoundError
        |-- ServiceNotDeletableError
        |-- AutoGraphAlreadyDeployedError
        |-- AutoGraphNotDeployedError
        |-- ModelConfigNotReadyError
        |-- AutoGraphBusyError
        |-- NoStrategiesError
        |-- CategoryAlreadyBuiltError
        |-- IngestionFailedError
        |-- JobStatusLostError
        |-- JobTimeoutError
        |-- AutoRagNotDeployedError
        `-- QueryFailedError

Choosing how precisely to catch

Catch at whichever level fits what you want to handle:

from arango_ai_sdk.exceptions import (
    ArangoAIError,
    AuthenticationError,
    InvalidCredentialsError,
)

try:
    ...
except InvalidCredentialsError:
    ...  # exactly: wrong username or password
except AuthenticationError:
    ...  # any authentication problem
except ArangoAIError:
    ...  # anything the SDK can raise

The families

AuthenticationError

Problems obtaining or using a token. See Authentication.

CommunicationError

Problems reaching the deployment or reading its reply. Its two children separate “never got there” from “got there, and it said no”:

PlatformUnreachableError

The deployment could not be reached within the retry budget, or did not answer within the request timeout. Nothing was rejected; nothing was reached.

ServiceError

A service was reached and answered with an error. Where the SDK knows what that error means for the call you made, it raises a more specific subclass, such as InvalidProjectNameError. Otherwise you get ServiceError itself.

What a ServiceError carries

Every ServiceError, including its subclasses, has two attributes in addition to its message:

status_code

The HTTP status code the service returned, or None.

error_code

The service’s own error number, where it sent one, or None.

from arango_ai_sdk.exceptions import ServiceError

try:
    ...
except ServiceError as exc:
    print(exc.status_code, exc.error_code, exc)

Concrete errors

InvalidCredentialsError

The deployment rejected the username or password. Never retried.

TokenRefreshError

A token was needed but could not be obtained or renewed.

DatabaseNotFoundError

The database named at client construction does not exist.

InvalidProjectNameError

A project name was rejected. See Creating a project.

ProjectNotFoundError

No project with the given name exists in the client’s database. See Getting a project.

InvalidSecretNameError

A secret profile name was rejected. See Creating a secret profile.

InvalidSecretValueError

A secret was rejected as empty or too long. The message never contains the secret. See Creating a secret profile.

SecretProfileNotFoundError

No secret profile with the given ID exists. See Getting a secret profile.

InvalidFileScopeError

A file scope breaks the platform’s rules. Normally raised before anything is sent, since the SDK applies the platform’s rules first. See Files.

InvalidFileMetadataError

The platform rejected the metadata attached to an upload. See Files.

EmptyFileError

The file to upload has no content. Normally raised before anything is sent. See Files.

FileBatchTooLargeError

A multi-file upload exceeds what one request may carry. Normally raised before anything is sent. See Files.

FileUploadFailedError

The platform could not store a file and reports having rolled the upload back. See Files.

Two local problems are reported with Python’s own exceptions rather than the SDK’s, because nothing was sent and the platform played no part: FileNotFoundError, IsADirectoryError and NotADirectoryError for a wrong path, and ValueError for a multi-file upload given no files.

InvalidServiceParametersError

The platform rejected a service install parameter. See Deploying AutoGraph and Deploying a retriever.

ServiceNotFoundError

The platform has no service with the ID it was asked to remove. See Removing AutoGraph and Removing a retriever.

ServiceNotDeletableError

The platform will not remove a service that another entity manages. See Removing AutoGraph.

AutoGraphAlreadyDeployedError

The project already has an AutoGraph service; a project has exactly one. Raised before anything is sent. See Deploying AutoGraph.

AutoGraphNotDeployedError

The project has no AutoGraph service to act on. Raised before anything is sent, by undeploy, wait_until_ready and every ingestion method. See Removing AutoGraph.

ModelConfigNotReadyError

AutoGraph refused to start a job because it cannot use its chat or embedding settings: a startup check found them invalid, or it is still loading them. Fix the settings or retry shortly. See Building the corpus.

AutoGraphBusyError

AutoGraph refused to start a job because a conflicting one is already running on the project. Which jobs conflict depends on the call. Wait for it and retry. See AutoGraph.

NoStrategiesError

The import was asked to run on categories that have no stored strategy. Run the strategizer first. See Importing the graph.

CategoryAlreadyBuiltError

The corpus build was asked to build a category that is already built, and incremental was False. See Building the corpus.

IngestionFailedError

A build or a strategy run ended as failed, or an import ended as failed or cancelled. job_status on the exception is the last status the platform returned for it. See Waiting for a step.

JobStatusLostError

The platform no longer has a status for the step being waited on, usually because the service restarted. job_id on the exception names it; the step itself may still be running. See Waiting for a step.

JobTimeoutError

The timeout passed to an ingestion method ran out before the step finished. The step keeps running on the platform. See Waiting for a step.

AutoRagNotDeployedError

The retriever this object is bound to is no longer in the project. Raised before anything is sent, by get, ask, undeploy and wait_until_ready; ask also raises it when the query endpoint answers 404. See Asking a question.

QueryFailedError

The retriever answered a question with a failure code instead of an answer, including on HTTP 200. failure_code is that code and run_id identifies the stored run. See Asking a question.

The full reference is in Exceptions.