Exceptions

Exceptions raised by the SDK.

Every exception the SDK raises descends from ArangoAIError, so one except always catches everything. Nothing from an underlying library (python-arango, requests, JSON parsing) is allowed to escape, it is translated into one of the types below first.

Exception capture happens in the corresponding namespace, so when a request to service A returns an error, none of the central modules should classify that error. This keeps the imports in the central communication and client modules clean.

The tree is deliberately shallow – a root, a few families, concrete errors underneath – so callers pick how precisely to catch:

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

The whole tree, in one place:

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

Root

exception arango_ai_sdk.exceptions.ArangoAIError

Base class for every exception raised by the SDK.

Authentication

exception arango_ai_sdk.exceptions.AuthenticationError

Bases: ArangoAIError

Base class for authentication problems.

exception arango_ai_sdk.exceptions.InvalidCredentialsError

Bases: AuthenticationError

The platform rejected the username or password.

Never retried: repeating a rejected login cannot succeed, and against some backends it counts towards a lockout.

exception arango_ai_sdk.exceptions.TokenRefreshError

Bases: AuthenticationError

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

Communication

exception arango_ai_sdk.exceptions.CommunicationError

Bases: ArangoAIError

Base class for problems reaching the platform or reading its reply.

exception arango_ai_sdk.exceptions.PlatformUnreachableError

Bases: CommunicationError

The platform could not be reached within the retry budget.

Distinct from InvalidCredentialsError: the platform never got the chance to reject anything.

exception arango_ai_sdk.exceptions.ServiceError(message, *, status_code=None, error_code=None)

Bases: CommunicationError

A service was reached and answered with an error.

The catch-all for error responses that is used if there is no named per-condition exception.

Parameters:
  • message (str) – Human-readable description of the failure.

  • status_code (int, optional) – HTTP status code returned by the service.

  • error_code (int, optional) – Service-specific error number, where one was supplied.

Return type:

None

exception arango_ai_sdk.exceptions.DatabaseNotFoundError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The database named at construction does not exist on the platform.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidProjectNameError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The service rejected the project name.

Raised from the projects namespace when create is called with a name the endpoint will not accept (empty, too long, or characters outside the allowed set).

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.ProjectNotFoundError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The project requested does not exist.

Raised when get is called with a name that has no project, and when AutoGraph install is asked for a project that is not there.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidSecretNameError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The service rejected the secret profile name.

Raised from the secret profile namespace when create is called with a name the endpoint will not accept (empty, too long, or characters outside letters, digits, spaces, underscores and hyphens).

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidSecretValueError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The service rejected the secret itself.

Raised from the secret profile namespace when create is called with a secret that is empty, whitespace only, or longer than 4096 characters. The message never contains the secret.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.SecretProfileNotFoundError(message, *, status_code=None, error_code=None)

Bases: ServiceError

No secret profile with the given ID exists on the platform.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidFileScopeError(message, *, status_code=None, error_code=None)

Bases: ServiceError

A file scope breaks the file service’s rules.

Raised from the files namespace, normally before anything is sent.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidFileMetadataError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The file service rejected the custom metadata attached to an upload.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.EmptyFileError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The file to upload has no content.

Raised from the files namespace, normally before anything is sent.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.FileBatchTooLargeError(message, *, status_code=None, error_code=None)

Bases: ServiceError

A multi-file upload exceeds what the file service accepts in one request.

Raised from the files namespace, normally before anything is sent. Split the files across several calls.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.FileUploadFailedError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The file service could not store the file and rolled the upload back.

Nothing is left behind, so no cleanup is needed before retrying.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.InvalidServiceParametersError(message, *, status_code=None, error_code=None)

Bases: ServiceError

ACP rejected an AutoGraph install parameter.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.ServiceNotFoundError(message, *, status_code=None, error_code=None)

Bases: ServiceError

No ACP service with the given ID exists on the platform.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.ServiceNotDeletableError(message, *, status_code=None, error_code=None)

Bases: ServiceError

ACP refused to delete a service managed by another entity.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.AutoGraphAlreadyDeployedError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The project already has an AutoGraph service; a project can have only one.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.AutoGraphNotDeployedError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The project has no AutoGraph service to act on.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.ModelConfigNotReadyError(message, *, status_code=None, error_code=None)

Bases: ServiceError

AutoGraph refused a job because its model configuration is not usable.

Either a startup probe found the chat or embedding settings invalid, or the service is still reloading them. Fix the settings or retry shortly.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.AutoGraphBusyError(message, *, status_code=None, error_code=None)

Bases: ServiceError

AutoGraph refused a job because another one holds the slot.

A build, strategizer run, orchestration or delete is already in progress for the project. Wait for it to finish and retry.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.NoStrategiesError(message, *, status_code=None, error_code=None)

Bases: ServiceError

AutoGraph refused to orchestrate because no strategy profiles are stored.

Run the strategizer for these categories first.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.CategoryAlreadyBuiltError(message, *, status_code=None, error_code=None)

Bases: ServiceError

AutoGraph refused to build a category that is already built.

Pass incremental=True to add to it.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.IngestionFailedError(message, *, job_status, status_code=None)

Bases: ServiceError

An AutoGraph job ended as failed or cancelled.

Parameters:
  • message (str) – Human-readable description of the failure.

  • job_status (Any) – The last status object the service returned for the job.

  • status_code (int, optional) – HTTP status code returned by the service.

Return type:

None

exception arango_ai_sdk.exceptions.JobStatusLostError(message, *, job_id, status_code=None)

Bases: ServiceError

AutoGraph no longer knows the job it was polled for.

The status record lives in pod memory and is gone after a restart, the job itself may still be running.

Parameters:
  • message (str) – Human-readable description of the failure.

  • job_id (str) – Id of the job whose status is gone.

  • status_code (int, optional) – HTTP status code returned by the service.

Return type:

None

exception arango_ai_sdk.exceptions.JobTimeoutError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The caller’s deadline passed before the job reached a terminal state.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.AutoRagNotDeployedError(message, *, status_code=None, error_code=None)

Bases: ServiceError

The retriever this AutoRag object is bound to is no longer in the project.

The project snapshot has no entry with its service id, so it was removed since the object was obtained.

Parameters:
  • message (str)

  • status_code (int | None)

  • error_code (int | None)

Return type:

None

exception arango_ai_sdk.exceptions.QueryFailedError(message, *, failure_code, run_id='', status_code=None)

Bases: ServiceError

The retriever answered the query with a failure instead of a result.

The service reports a provider problem hit mid-query, such as an expired key or exhausted quota, as a 200 with a non-empty error_code. The SDK turns that into this exception so a failed query never reads as an empty answer.

Parameters:
  • message (str) – Human-readable description of the failure.

  • failure_code (str) – The machine-readable code the service returned, e.g. "INSUFFICIENT_QUOTA" or "PROCESSING_ERROR".

  • run_id (str) – Identifier of the persisted query run, empty when none was stored.

  • status_code (int, optional) – HTTP status code returned by the service.

Return type:

None