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:
ArangoAIErrorBase class for authentication problems.
- exception arango_ai_sdk.exceptions.InvalidCredentialsError¶
Bases:
AuthenticationErrorThe 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:
AuthenticationErrorA token was needed but could not be obtained or renewed.
Communication¶
- exception arango_ai_sdk.exceptions.CommunicationError¶
Bases:
ArangoAIErrorBase class for problems reaching the platform or reading its reply.
- exception arango_ai_sdk.exceptions.PlatformUnreachableError¶
Bases:
CommunicationErrorThe 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:
CommunicationErrorA 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorNo 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:
ServiceErrorA 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorA 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:
ServiceErrorThe 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:
ServiceErrorACP 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:
ServiceErrorNo 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:
ServiceErrorACP 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorAutoGraph 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:
ServiceErrorAutoGraph 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:
ServiceErrorAutoGraph 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:
ServiceErrorAutoGraph refused to build a category that is already built.
Pass
incremental=Trueto 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:
ServiceErrorAn 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:
ServiceErrorAutoGraph 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:
ServiceErrorThe 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:
ServiceErrorThe 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:
ServiceErrorThe 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
200with a non-emptyerror_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