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¶
AuthenticationErrorProblems obtaining or using a token. See Authentication.
CommunicationErrorProblems reaching the deployment or reading its reply. Its two children separate “never got there” from “got there, and it said no”:
PlatformUnreachableErrorThe deployment could not be reached within the retry budget, or did not answer within the request timeout. Nothing was rejected; nothing was reached.
ServiceErrorA 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 getServiceErroritself.
What a ServiceError carries¶
Every ServiceError, including its subclasses,
has two attributes in addition to its message:
status_codeThe HTTP status code the service returned, or
None.error_codeThe 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¶
InvalidCredentialsErrorThe deployment rejected the username or password. Never retried.
TokenRefreshErrorA token was needed but could not be obtained or renewed.
DatabaseNotFoundErrorThe database named at client construction does not exist.
InvalidProjectNameErrorA project name was rejected. See Creating a project.
ProjectNotFoundErrorNo project with the given name exists in the client’s database. See Getting a project.
InvalidSecretNameErrorA secret profile name was rejected. See Creating a secret profile.
InvalidSecretValueErrorA secret was rejected as empty or too long. The message never contains the secret. See Creating a secret profile.
SecretProfileNotFoundErrorNo secret profile with the given ID exists. See Getting a secret profile.
InvalidFileScopeErrorA file scope breaks the platform’s rules. Normally raised before anything is sent, since the SDK applies the platform’s rules first. See Files.
InvalidFileMetadataErrorThe platform rejected the metadata attached to an upload. See Files.
EmptyFileErrorThe file to upload has no content. Normally raised before anything is sent. See Files.
FileBatchTooLargeErrorA multi-file upload exceeds what one request may carry. Normally raised before anything is sent. See Files.
FileUploadFailedErrorThe 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.
InvalidServiceParametersErrorThe platform rejected a service install parameter. See Deploying AutoGraph and Deploying a retriever.
ServiceNotFoundErrorThe platform has no service with the ID it was asked to remove. See Removing AutoGraph and Removing a retriever.
ServiceNotDeletableErrorThe platform will not remove a service that another entity manages. See Removing AutoGraph.
AutoGraphAlreadyDeployedErrorThe project already has an AutoGraph service; a project has exactly one. Raised before anything is sent. See Deploying AutoGraph.
AutoGraphNotDeployedErrorThe project has no AutoGraph service to act on. Raised before anything is sent, by
undeploy,wait_until_readyand every ingestion method. See Removing AutoGraph.ModelConfigNotReadyErrorAutoGraph 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.
AutoGraphBusyErrorAutoGraph 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.
NoStrategiesErrorThe import was asked to run on categories that have no stored strategy. Run the strategizer first. See Importing the graph.
CategoryAlreadyBuiltErrorThe corpus build was asked to build a category that is already built, and
incrementalwasFalse. See Building the corpus.IngestionFailedErrorA build or a strategy run ended as failed, or an import ended as failed or cancelled.
job_statuson the exception is the last status the platform returned for it. See Waiting for a step.JobStatusLostErrorThe platform no longer has a status for the step being waited on, usually because the service restarted.
job_idon the exception names it; the step itself may still be running. See Waiting for a step.JobTimeoutErrorThe
timeoutpassed to an ingestion method ran out before the step finished. The step keeps running on the platform. See Waiting for a step.AutoRagNotDeployedErrorThe retriever this object is bound to is no longer in the project. Raised before anything is sent, by
get,ask,undeployandwait_until_ready;askalso raises it when the query endpoint answers404. See Asking a question.QueryFailedErrorThe retriever answered a question with a failure code instead of an answer, including on HTTP 200.
failure_codeis that code andrun_ididentifies the stored run. See Asking a question.
The full reference is in Exceptions.